qi-coding-agent 0.1.0__tar.gz

qi_coding_agent-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,115 @@
+name: publish
+
+# 发布四个 distribution:qi-coding-agent(core)+ qi-mcp / qi-agents / qi-web。
+# 锁步同版本;先构建校验,再按目标索引发布。
+#
+# 触发:
+#   - push tag `v*`  → 发布到 PyPI(正式)
+#   - workflow_dispatch → 手选 testpypi / pypi(试跑用 testpypi)
+#
+# `packages` 默认只发 core(qi-coding-agent)。要连三个官方扩展一起发,把它切成 `all` ——
+# 那要求 PyPI 上四个发行名都配好了 trusted publisher(扩展还没发时就保持 core)。
+#
+# 首次发布前要在 PyPI / TestPyPI 各配一次 **Trusted Publisher**(不需要 API token):
+#   Owner: viewnah · Repository: qi · Workflow: publish.yml · Environment: pypi(或 testpypi)
+# 本文件用 OIDC(id-token)发布,所以两个 job 都声明了 `environment`。
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: 发布到哪个索引
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+      packages:
+        description: 发哪些包(core = 只发 qi-coding-agent;all = 连三个官方扩展)
+        type: choice
+        options: [core, all]
+        default: core
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: 校验 + 构建
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262  # v4
+        with:
+          persist-credentials: false      # 构建阶段用不到 git 凭证,别把它写进产物
+
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+        with:
+          enable-cache: false             # 发布 job 不开缓存(缓存投毒在这里代价最高)
+
+      - name: 版本一致性(发 core 时只核 core;发 all 时要求四个锁步;tag 触发时顺带核 tag)
+        env:
+          TAG: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
+          PACKAGES: ${{ inputs.packages || 'core' }}
+        run: |
+          if [ "$PACKAGES" = "all" ]; then
+            python3 scripts/check_versions.py
+          else
+            python3 scripts/check_versions.py --only core
+          fi
+
+      - name: 构建(按 packages 选择)
+        env:
+          PACKAGES: ${{ inputs.packages || 'core' }}
+        run: |
+          uv build --out-dir dist
+          if [ "$PACKAGES" = "all" ]; then
+            uv build extensions/qi-mcp    --out-dir dist
+            uv build extensions/qi-agents --out-dir dist
+            uv build extensions/qi-web    --out-dir dist
+          fi
+
+      - name: 产物清单
+        run: ls -l dist
+
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: 发布到 TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write                      # OIDC 信任发布,不用 token
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+          skip-existing: true              # 重跑同一版本不炸
+
+  publish-pypi:
+    name: 发布到 PyPI
+    needs: build
+    if: >-
+      github.ref_type == 'tag' ||
+      (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # release/v1
+        with:
+          packages-dir: dist/

qi_coding_agent-0.1.0/.gitignore

@@ -0,0 +1,35 @@
+# qi 运行时产物
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.python-version
+
+# 运行时配置/数据(不入库;agent 样例在 examples/agents/)
+.qi/
+
+# qi-web 前端构建产物(generated:先 `cd web && npm run build` 再打包)
+# 不纳入版本控制;缺失时 `qi web` 会提示去构建,而不是给一个坏页面
+src/qi_agent/web/static/
+
+# 已有忽略(参考组件)
+sdk/
+data/
+
+# pi 自身的运行期目录(tasks 输出等,非源码)
+.pi/
+
+# qi-web 前端依赖与构建中间产物
+extensions/qi-web/ui/node_modules/
+extensions/qi-web/ui/dist/
+
+# 编辑器配置
+.vscode/
+
+# vitest 输出(node 侧测试报告;含绝对路径与时间戳,不入库)。
+# 旧 core web 与 qi-web 扩展两条路径都要盖。
+web/.vitest/
+extensions/qi-web/ui/.vitest/

qi_coding_agent-0.1.0/.pi-lens.json

@@ -0,0 +1,11 @@
+{
+  "ignore": [
+    "src/qi_agent/web/static/**",
+    "extensions/qi-web/ui/node_modules/**",
+    "extensions/qi-web/ui/dist/**",
+    "**/*.min.js"
+  ],
+  "format": {
+    "enabled": false
+  }
+}

qi_coding_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 viewnah
+
+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_coding_agent-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: qi-coding-agent
+Version: 0.1.0
+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
+
+**用 Python 写的编码 agent 框架**。给它一个目标和一个工作目录,它会读文件、跑命令、改内容,一步步把任务做完。
+
+**core 就是单 agent**:会话(JSONL + 分支树)、工具循环、系统提示词、CLI 与 TUI、压缩、认证都在里面;
+角色 / MCP / Web 这类增值功能全部走**扩展**,不塞进 core。
+
+> **发行名是 `qi-coding-agent`** —— PyPI 上的 `qi-agent` 属于**别的项目**,别装错;
+> import 包名仍是 `qi_agent`、命令仍是 `qi`。现在还没发布,所以以**从源码安装**为主(见下)。
+> `qi-mcp` / `qi-agents` / `qi-web` 是三个独立官方 pip 包,各自带自己的手册。
+
+## 装
+
+前置:**Python ≥ 3.12** 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+git clone https://github.com/viewnah/qi.git
+cd qi
+uv sync                  # 把 qi 装成 editable;`uv run qi …` 直接可用
+uv run qi doctor         # 冒烟:配置 / 凭证 / 扩展 / 包声明,一次全报
+```
+
+官方扩展**按需单独装**(core 不内置、不默认装):
+
+```bash
+pip install -e extensions/qi-agents -e extensions/qi-mcp -e extensions/qi-web
+uv run qi doctor         # 「声明了但没装」「装了但没声明」都在这里报出来,并给出装法
+```
+
+**发布之后**(现在还没有)可以直接装发行版,扩展用 `--with` 一次装齐:
+
+```bash
+uv tool install qi-coding-agent                       # 只装 core
+uv tool install qi-coding-agent --with qi-mcp --with qi-agents
+```
+
+装法(自家 venv / `uv tool` / 只读解释器)与声明层(`settings.packages`)的差别见
+[docs/packages.md](docs/packages.md)。
+
+## 快速开始
+
+```bash
+uv run qi init                 # 引导:选 provider → 加模型 → 设为默认(写 models.json + settings.json + auth.json)
+uv run qi init --list-presets  # 看内置的预置 provider(国产为主:deepseek / qwen / kimi / glm / minimax …)
+uv run qi init --preset deepseek   # 一条命令物化预置并设为默认(只补缺、幂等)
+uv run qi doctor               # 校验配置与凭证
+```
+
+然后三种跑法:
+
+```bash
+uv run qi                      # 交互界面(裸 qi 就是界面)
+uv run qi "分析这个仓库"        # 进界面,并把这句话作为首条消息发出
+uv run qi -p "分析这个仓库"     # 无头一次:stdout 只有答案(进度走 stderr)
+uv run qi --mode json "…"      # 事件流:一行一个 JSON,喂给上层程序
+```
+
+不用交互时:
+
+```bash
+uv run qi init -y --provider my-proxy --model my-model \
+    --base-url https://my-proxy.internal/v1 --api openai-completions --api-key sk-xxx
+```
+
+**零配置也能跑**:基座提示词在代码里,不写任何配置就是一个能用的单 agent。
+逐步说明见 [docs/quickstart.md](docs/quickstart.md)。
+
+## 怎么定制
+
+| 想做 | 用 | 看 |
+| --- | --- | --- |
+| 改偏好(渲染模式、压缩、思考级别…) | `/settings`、`settings.json` | [设置](docs/settings.md) · [配置](docs/configuration.md) |
+| 换模型 / 接本地模型 / 自建代理 | `models.json`、`qi init --preset` | [选一个模型](docs/models.md) |
+| 给它一份按需加载的检查清单 | 一个含 `SKILL.md` 的目录 | [技能](docs/skills.md) |
+| 加自己的工具 / 命令 / 事件钩子 | `extension.py` 里的 `register(api)` | [写扩展](docs/extensions.md) · [终端 UI 组件](docs/tui.md) |
+| 换配色 | `theme`、`QI_THEME` | [主题](docs/themes.md) |
+| 装 / 声明 / 分发扩展 | `qi install`、`settings.packages` | [扩展的安装与声明](docs/packages.md) |
+
+可跑的样例:[`examples/extensions/hello/`](examples/extensions/hello/) —— 一份 `extension.py` 把主要的面各走一遍。
+
+## 官方扩展
+
+| 扩展 | 提供什么 | 手册 |
+| --- | --- | --- |
+| `qi-agents` | 角色(`agent.md`)+ 委派子任务 | [README](extensions/qi-agents/README.md) |
+| `qi-mcp` | MCP server 接入(代理工具 / 直连工具) | [README](extensions/qi-mcp/README.md) |
+| `qi-web` | HTTP 宿主 + 官方 Web UI | [README](extensions/qi-web/README.md) |
+
+装完之后:`qi list` 看装了哪些、`qi doctor` 看声明与实装是否一致。
+
+## 安全
+
+三条要知道的(完整模型见 [docs/security.md](docs/security.md)):
+
+- **`bash` 不筛命令**:内置 bash 以 qi 进程权限执行任意命令 —— 所谓"半沙箱"最容易被误当成安全边界。
+  要收紧就用工具白名单(`-t` / `-xt` / `-nt` / `-nbt`、`settings.defaultTools`,或角色 `tools:`),
+  要真边界就**把 qi 放进容器 / VM / 受限用户**([docs/containerization.md](docs/containerization.md))。
+- **扩展就是任意代码,角色正文是仓库控制的提示词**:只装可信来源。项目级 `.qi/extensions/` **未信任不加载**
+  (`qi -a` 信任、`-na` 拒绝;没表态时看 `settings.defaultProjectTrust`,`ask` 在无头下保守判不信任)。
+- **凭证三源**:auth store(`~/.qi/agent/auth.json`,0600)→ 约定环境变量 → `models.json` 的 `apiKey` 引用;
+  配置文件与导出包**零明文**([docs/providers.md](docs/providers.md))。
+
+## 文档
+
+| 去处 | 内容 |
+| --- | --- |
+| [docs/index.md](docs/index.md) | **手册**:开始 / 指南(运行 · 定制 · 构建)/ 参考 |
+| [docs/how-qi-works.md](docs/how-qi-works.md) | agent loop、上下文、会话、工具、信任 —— 先读这一页 |
+| [design/overview.md](design/overview.md) | 总设计:架构总览、既定决策索引、技术选型、目录布局、安全总原则 |
+| [design/PLAN.md](design/PLAN.md) | 开发计划、阶段表、未决清单 |
+| [design/pi-alignment.md](design/pi-alignment.md) | 与上游 pi 的逐节对照(设计口径,不进手册) |
+| [design/development.md](design/development.md) | 怎么跑源码 / 测试 / 静态检查 / 仓库布局 |
+| [extensions/](extensions/) | 官方扩展与各自的手册 |
+| [examples/](examples/) | 教学样例(不自动加载) |
+
+**两轨边界**:`docs/` 写给**使用者与模型**(随 wheel 发布,索引会注入提示词);`design/` 写给**改动者**
+(不进 wheel、不注入提示词)。扩展的手册归**扩展自己**,core 的 `docs/` 只讲机制。
+
+## 许可
+
+MIT(见 [LICENSE](LICENSE))。

qi_coding_agent-0.1.0/README.md

@@ -0,0 +1,121 @@
+# qi
+
+**用 Python 写的编码 agent 框架**。给它一个目标和一个工作目录,它会读文件、跑命令、改内容,一步步把任务做完。
+
+**core 就是单 agent**:会话(JSONL + 分支树)、工具循环、系统提示词、CLI 与 TUI、压缩、认证都在里面;
+角色 / MCP / Web 这类增值功能全部走**扩展**,不塞进 core。
+
+> **发行名是 `qi-coding-agent`** —— PyPI 上的 `qi-agent` 属于**别的项目**,别装错;
+> import 包名仍是 `qi_agent`、命令仍是 `qi`。现在还没发布,所以以**从源码安装**为主(见下)。
+> `qi-mcp` / `qi-agents` / `qi-web` 是三个独立官方 pip 包,各自带自己的手册。
+
+## 装
+
+前置:**Python ≥ 3.12** 与 [uv](https://docs.astral.sh/uv/)。
+
+```bash
+git clone https://github.com/viewnah/qi.git
+cd qi
+uv sync                  # 把 qi 装成 editable;`uv run qi …` 直接可用
+uv run qi doctor         # 冒烟:配置 / 凭证 / 扩展 / 包声明,一次全报
+```
+
+官方扩展**按需单独装**(core 不内置、不默认装):
+
+```bash
+pip install -e extensions/qi-agents -e extensions/qi-mcp -e extensions/qi-web
+uv run qi doctor         # 「声明了但没装」「装了但没声明」都在这里报出来,并给出装法
+```
+
+**发布之后**(现在还没有)可以直接装发行版,扩展用 `--with` 一次装齐:
+
+```bash
+uv tool install qi-coding-agent                       # 只装 core
+uv tool install qi-coding-agent --with qi-mcp --with qi-agents
+```
+
+装法(自家 venv / `uv tool` / 只读解释器)与声明层(`settings.packages`)的差别见
+[docs/packages.md](docs/packages.md)。
+
+## 快速开始
+
+```bash
+uv run qi init                 # 引导:选 provider → 加模型 → 设为默认(写 models.json + settings.json + auth.json)
+uv run qi init --list-presets  # 看内置的预置 provider(国产为主:deepseek / qwen / kimi / glm / minimax …)
+uv run qi init --preset deepseek   # 一条命令物化预置并设为默认(只补缺、幂等)
+uv run qi doctor               # 校验配置与凭证
+```
+
+然后三种跑法:
+
+```bash
+uv run qi                      # 交互界面(裸 qi 就是界面)
+uv run qi "分析这个仓库"        # 进界面,并把这句话作为首条消息发出
+uv run qi -p "分析这个仓库"     # 无头一次:stdout 只有答案(进度走 stderr)
+uv run qi --mode json "…"      # 事件流:一行一个 JSON,喂给上层程序
+```
+
+不用交互时:
+
+```bash
+uv run qi init -y --provider my-proxy --model my-model \
+    --base-url https://my-proxy.internal/v1 --api openai-completions --api-key sk-xxx
+```
+
+**零配置也能跑**:基座提示词在代码里,不写任何配置就是一个能用的单 agent。
+逐步说明见 [docs/quickstart.md](docs/quickstart.md)。
+
+## 怎么定制
+
+| 想做 | 用 | 看 |
+| --- | --- | --- |
+| 改偏好(渲染模式、压缩、思考级别…) | `/settings`、`settings.json` | [设置](docs/settings.md) · [配置](docs/configuration.md) |
+| 换模型 / 接本地模型 / 自建代理 | `models.json`、`qi init --preset` | [选一个模型](docs/models.md) |
+| 给它一份按需加载的检查清单 | 一个含 `SKILL.md` 的目录 | [技能](docs/skills.md) |
+| 加自己的工具 / 命令 / 事件钩子 | `extension.py` 里的 `register(api)` | [写扩展](docs/extensions.md) · [终端 UI 组件](docs/tui.md) |
+| 换配色 | `theme`、`QI_THEME` | [主题](docs/themes.md) |
+| 装 / 声明 / 分发扩展 | `qi install`、`settings.packages` | [扩展的安装与声明](docs/packages.md) |
+
+可跑的样例:[`examples/extensions/hello/`](examples/extensions/hello/) —— 一份 `extension.py` 把主要的面各走一遍。
+
+## 官方扩展
+
+| 扩展 | 提供什么 | 手册 |
+| --- | --- | --- |
+| `qi-agents` | 角色(`agent.md`)+ 委派子任务 | [README](extensions/qi-agents/README.md) |
+| `qi-mcp` | MCP server 接入(代理工具 / 直连工具) | [README](extensions/qi-mcp/README.md) |
+| `qi-web` | HTTP 宿主 + 官方 Web UI | [README](extensions/qi-web/README.md) |
+
+装完之后:`qi list` 看装了哪些、`qi doctor` 看声明与实装是否一致。
+
+## 安全
+
+三条要知道的(完整模型见 [docs/security.md](docs/security.md)):
+
+- **`bash` 不筛命令**:内置 bash 以 qi 进程权限执行任意命令 —— 所谓"半沙箱"最容易被误当成安全边界。
+  要收紧就用工具白名单(`-t` / `-xt` / `-nt` / `-nbt`、`settings.defaultTools`,或角色 `tools:`),
+  要真边界就**把 qi 放进容器 / VM / 受限用户**([docs/containerization.md](docs/containerization.md))。
+- **扩展就是任意代码,角色正文是仓库控制的提示词**:只装可信来源。项目级 `.qi/extensions/` **未信任不加载**
+  (`qi -a` 信任、`-na` 拒绝;没表态时看 `settings.defaultProjectTrust`,`ask` 在无头下保守判不信任)。
+- **凭证三源**:auth store(`~/.qi/agent/auth.json`,0600)→ 约定环境变量 → `models.json` 的 `apiKey` 引用;
+  配置文件与导出包**零明文**([docs/providers.md](docs/providers.md))。
+
+## 文档
+
+| 去处 | 内容 |
+| --- | --- |
+| [docs/index.md](docs/index.md) | **手册**:开始 / 指南(运行 · 定制 · 构建)/ 参考 |
+| [docs/how-qi-works.md](docs/how-qi-works.md) | agent loop、上下文、会话、工具、信任 —— 先读这一页 |
+| [design/overview.md](design/overview.md) | 总设计:架构总览、既定决策索引、技术选型、目录布局、安全总原则 |
+| [design/PLAN.md](design/PLAN.md) | 开发计划、阶段表、未决清单 |
+| [design/pi-alignment.md](design/pi-alignment.md) | 与上游 pi 的逐节对照(设计口径,不进手册) |
+| [design/development.md](design/development.md) | 怎么跑源码 / 测试 / 静态检查 / 仓库布局 |
+| [extensions/](extensions/) | 官方扩展与各自的手册 |
+| [examples/](examples/) | 教学样例(不自动加载) |
+
+**两轨边界**:`docs/` 写给**使用者与模型**(随 wheel 发布,索引会注入提示词);`design/` 写给**改动者**
+(不进 wheel、不注入提示词)。扩展的手册归**扩展自己**,core 的 `docs/` 只讲机制。
+
+## 许可
+
+MIT(见 [LICENSE](LICENSE))。