Metadata-Version: 2.4
Name: xiaoyu-agent
Version: 0.68.0
Summary: 小羽 — a harness coding agent
License-Expression: MIT
Project-URL: Homepage, https://xiaoyu.openapi.click
Project-URL: Repository, https://github.com/pholex/zhinu
Project-URL: Issues, https://github.com/pholex/zhinu/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai==3.23.0
Requires-Dist: anthropic==1.9.0
Requires-Dist: tree-sitter>=0.22
Requires-Dist: tree-sitter-bash>=0.21
Provides-Extra: sdk
Requires-Dist: jsonschema==4.26.0; extra == "sdk"
Provides-Extra: tui
Requires-Dist: prompt_toolkit==3.0.53; extra == "tui"
Requires-Dist: rich==15.0.0; extra == "tui"
Provides-Extra: browser
Requires-Dist: playwright==1.63.0; extra == "browser"
Provides-Extra: bedrock
Requires-Dist: boto3==1.43.105; extra == "bedrock"
Requires-Dist: botocore==1.43.105; extra == "bedrock"
Provides-Extra: otel
Requires-Dist: opentelemetry-sdk>=1.45.0; extra == "otel"
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.45.0; extra == "otel"
Provides-Extra: serve
Requires-Dist: fastapi==0.141.1; extra == "serve"
Requires-Dist: uvicorn==0.54.0; extra == "serve"
Requires-Dist: websockets==17.1; extra == "serve"
Dynamic: license-file

<!-- 图标用 raw 绝对 URL：PyPI 项目页不解析仓库相对路径；GitHub 亮暗主题
     经 picture 双源切换（currentColor 版经 img 加载会落成黑色，暗色下隐身，
     所以这里用写死填充色的两个变体；registry 权威副本在 docs/acp-registry/） -->
# <picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pholex/zhinu/main/docs/assets/feather-dark.svg"><img src="https://raw.githubusercontent.com/pholex/zhinu/main/docs/assets/feather-light.svg" width="30" alt=""></picture> 小羽 · Xiaoyu

[![ci](https://github.com/pholex/zhinu/actions/workflows/ci.yml/badge.svg)](https://github.com/pholex/zhinu/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/xiaoyu-agent)](https://pypi.org/project/xiaoyu-agent/)
[![website](https://img.shields.io/badge/website-xiaoyu.openapi.click-1f6feb)](https://xiaoyu.openapi.click)

> **Zhinu Coding Agent | Token Weaver of the Universe**<br>
> Weaving code, connecting dots, and showing you the best harness architecture.
>
> 一个自研的 harness coding agent：<br>
> 终端里可交互、可无人值守，也可作为库嵌进您自己的程序，支持多会话并行。<br>
> 依赖极简，适配 Windows / macOS / Linux 全平台。
>
> 命名两层：**织女 Zhinu 是织坊里的一群 Weaver，小羽 Xiaoyu 是其中一员**——harness 是她织机上的提综装置，梭子带着 token 当纬线穿行。<br>
> 小羽**既是织手（Agent），也带着自己的织机（Platform）**：自己能织，也能让你把自己的产品架在她的织机上织。

各大模型厂商都在做自己的 coding agent、深度绑定自家模型；行业通用的那些又越做越重——订阅、账号体系，连模型也一并卖给你。小羽反着来：**harness 内核一样不少，商业外壳一概没有**——不订阅、不登录，key 是你自己的，模型你自己挑、随时换。

安全护栏也在往同一个方向加码：确认框越堆越多、越来越难关掉，体验被一点点吃掉。小羽把这个选择权交还给你——**`--yolo` 一档做满**，不问、不停、不降速，而沙箱与不可逆命令拦截在这一档下照样兜着。

再往前看一步：**每个行业、每个企业迟早都要有自己的 coding agent**——懂自己的代码库、自己的规范、自己的工具链和审批流程，这件事外人替你做不了。小羽想当的是那层内核：agent 该有的一整套（工具、沙箱、审批、上下文管理、MCP 与技能）现成给你，模型、工具、流程你自己往上接，而不是从零再写一遍 harness。

## 安装

```bash
pip install "xiaoyu-agent[tui,serve]" xiaoyu-agent-sdk
```

`xiaoyu-agent-sdk` 是嵌入 SDK，装上就能在自己的 Python 程序里 `import xiaoyu_agent_sdk` 驱动小羽（见 [SDK 指南](docs/sdk.md)）；它与本体同版本发布、精确钉住本体版本，`xiaoyu update` / `xiaoyu uninstall` 会连它一起升级、卸载。其它可选组件：`[bedrock]`、`[browser]`、`[otel]`。

升级与卸载：

```bash
xiaoyu update                     # 升级
xiaoyu uninstall                  # 卸载；加 --purge 连配置一起删
```

装完跑 `xiaoyu doctor` 体检一遍；`xiaoyu term install` 把 Tab 补全和终端集成（`@x` / `@c`）一起写进 shell 启动文件（bash / zsh / fish）。连不上模型时用 `xiaoyu doctor --probe` 真发一条请求排查；报 issue 时用 `xiaoyu doctor --bundle` 打诊断包（含路径与命令历史，分享前看一眼）。

## 配置

```bash
xiaoyu config             # 交互向导（落盘前先对主模型发一条最小请求验证，--no-probe 跳过）
xiaoyu config --show      # 看生效配置与来源（key 永不回显）
```

用户级 `.env`：macOS / Linux 在 `~/.config/xiaoyu/.env`，Windows 在 `%APPDATA%\xiaoyu\.env`。

最短路径是直连厂商，填一个 key 就能跑：

```ini
DEEPSEEK_API_KEY=<your-key>
```

内置直连 deepseek / moonshot / qwen / zhipu / anthropic / gemini / openai / xai，键名一律用厂商原生名；AWS Bedrock 上的 Claude 可以不要 key、只凭 AWS 凭证链（`XIAOYU_BEDROCK_REGION=us-east-1`），或用 Bedrock API key（`AWS_BEARER_TOKEN_BEDROCK`），详见 [docs/configuration.md](docs/configuration.md)。或者走 OpenAI 兼容网关：

```ini
XIAOYU_BASE_URL=https://<你的网关>/v1
XIAOYU_MODEL=<你网关上的模型名>
XIAOYU_API_KEY=<your-key>
```

直连和网关至少配一个；**两个都配时清单自动合并**，同名模型直连优先、网关兜底。两个都没配时启动会报 MissingConfig，运行 `xiaoyu config` 按向导填即可。

## 用

```bash
xiaoyu                                  # 交互（xy 是等价缩写）
xy "把 utils.py 里的类型注解补全"          # 一次性执行（-p/--prompt 是等价拼写，兼容抄来的脚本）
git diff | xy "写一条 commit message"     # 管道内容当材料
xy --output-format json "总结这个仓库"     # 或 stream-json（NDJSON 事件流）
xy --output-schema schema.json "给这个仓库打分"   # 按 JSON Schema 收尾，结果在 output 字段（脚本/CI 用）
xy resume --last "继续把测试修完"
xy resume 20261006-101500-12345          # 按会话 id 接回：开场和退出时「接回本会话」那行给的就是这条命令
xy resume nightly                        # 具名会话按名字接回（-s 起的名字、终端集成的 term-…）
xy -s nightly "跑一下回归"                # 命名会话：同名接着聊，脚本反复调用用它

xiaoyu sessions                         # 列出本机会话
xiaoyu sessions export 1 > chat.md      # 导出一场历史会话（Markdown / --format json，不含 system 提示）
xiaoyu sessions inspect 1 --errors     # 按原始行号诊断失败请求、工具错误与拒绝；--raw 展开脱敏记录
xiaoyu sessions rename 1 "登录页修复"   # 给它起个名字，resume 列表里代替首条消息
xy --stats "跑一下测试"                  # 收尾多一行：耗时 / 首 token / 输出 tok/s（交互模式也认）
xiaoyu send zhinu-1 "顺便把 lint 跑一下"  # 给另一个终端里的小羽递话

xiaoyu mcp add chrome-devtools --scope user npx -y chrome-devtools-mcp@latest
xiaoyu mcp list                         # 写的就是 .mcp.json / mcp.json
xiaoyu mcp probe chrome-devtools        # 不经模型直接握手、列工具；--script 按脚本调用并逐步输出 JSON

xiaoyu term install                     # 把终端集成与 Tab 补全写进 ~/.zshrc 等启动文件（先给你过目再写）：之后在自己的 shell 里
@x 刚才那个报错怎么回事                   # 随时提问，带着刚跑过的命令，续写同一会话；见 docs/terminal-integration.md
@c 找出大于 100M 的文件，按大小倒序        # 一句话换一条命令，放回你的提示符，回车才执行（zsh / bash）
```

REPL 里：`/help` `/tools` `/skills` `/model` `/search` `/effort` `/mode` `/usage` `/context` `/compact` `/copy` `/export` `/clear` `/exit` `/tasks` `/plan` `/goal` `/perm` `/allow` `/deny` `/resume` `/rewind` `/mcp` `/quit`

第一次用，想先看它怎么干活：[examples/first-task](examples/first-task/)——一个带着一个失败测试的小项目，照 README 跑一遍，五分钟。

无人值守时没人按确认键：先用 `/allow` 配规则，或 `--mode auto`、`--yolo`。放进 CI 跑见 [docs/ci.md](docs/ci.md)（附 GitHub Actions 样本）。

## 模式：放手程度你定

打开就是 **auto** 档；确认 / auto / plan 用 Shift-Tab 循环切换，或 `/mode`、`--mode` 起手，
`XIAOYU_MODE=default` 改个人默认；`--yolo` 单独开。

| 档 | 会不会问你 |
|---|---|
| **auto**（出厂默认） | 工作区内改文件、沙箱内跑命令免确认；危险命令、提权、到远程主机上执行、写到工作区外仍要问 |
| **确认** | 写文件、执行命令逐条确认 |
| **plan** | 只读规划态：交计划后要你批准才执行 |
| **`--yolo`** | 全放行，一路跑到底 |
| **`--unguarded`** | 无护栏预设：硬红线、必问点、沙箱、信任门一并放开，只在编排环境注入 `XIAOYU_UNGUARDED=1` 时生效（见 [docs/security.md](docs/security.md)） |

auto 档**放行的依据是沙箱，不是信任**——沙箱不可用时自动降级成只有改文件免确认。

## `--yolo`：自动化给满

商业化产品把"每步都要你确认"当成必选项；小羽把它当成一档——你可以选择完全不确认。`--yolo` 是做满的一档：不问、不停、不降速，无人值守、CI、容器里就该这么跑。

它也不是无政府，四条底线**在 `--yolo` 下照样生效**：

- bash 仍在内核级沙箱里（除非你人工批准一次升权），写不出工作区、临时目录和构建缓存
- `deny` 权限规则一条都不放行
- `rm -rf /`、fork bomb 一类不可逆命令任何模式下都不执行
- 计划批准（`exit_plan_mode`）仍要问；跨会话消息默认不收

所以 `--yolo` 的实际风险面是"沙箱内能做的一切 + 联网"——介意联网就 `--no-network`。

## 大致能做什么

- **工具组**：读 / grep / glob / 精确替换 / 写文件 / bash（Windows 换 PowerShell）/ 任务清单；`explore` 子 agent 把检索委托给便宜模型；`web_search` 联网，`x_search` 查 X 帖子，Gemini Deep Research 支持后台研究与报告查询（见[配置](docs/configuration.md)）
- **后台任务**：bash 加 `run_in_background` 立即返回接着干别的，完成自动通知（不用轮询）；`monitor` 盯 CI / tail 日志，事件逐行送达并自动限流；`/tasks` 查看、`kill_task` 终止
- **编辑不出岔子**：改前必须完整读过，替换目标不唯一或文件被外部改动即打回
- **沙箱**：bash 跑在内核级沙箱里（macOS Seatbelt / Linux bubblewrap），只能写工作区、临时目录和构建缓存；`--no-network` 可断网
- **长会话不断片**：上下文快满时分层回收，Ctrl-C 随时可继续，`xiaoyu resume` 恢复历史会话
- **出错自己扛**：限流 / 瞬时错误自动重试，配了降级链就换模型接着跑
- **多协议**：按型号自动选 chat completions / Responses / Anthropic Messages，推理状态回传与 prompt caching 都用得上
- **图片输入**：TUI 里 Ctrl-V 贴截图（Windows 上用 Alt-V——终端把 Ctrl-V 留给了文本粘贴）、拖文件进终端；一次性模式用 `--image 图.png`（可重复）或 `--paste`（取系统剪贴板）随指令发图；MCP 工具返回的图也送到模型眼前
- **可扩展**：SKILL.md 技能、`pip install` 即挂载的工具包、MCP server（`mcpServers` 格式与主流 agent 客户端通用，含 OSV 检查与 rug-pull 隔离）；MCP 工具默认走检索模式——不塞满 schema，模型用 `search_tool` 按需检索、`use_tool` 调用，几百个工具也不吃上下文
- **插件包**：`xiaoyu plugin add aws/agent-toolkit-for-aws --name aws-core` 一行装齐技能 + MCP 声明，`plugin update` 拉新。认 [agent-plugins.org](https://agent-plugins.org) 的跨客户端 bundle 格式，社区已有的包直接能用；MCP 声明默认不装，摊出命令行问过才写
- **多 agent 织造**：声明式 subagent（`agents/*.toml` 放一个文件就多一个可委托的子 agent，带 worktree 隔离与 resume 续跑）；**七襄·并行织造模式**（Qixiang · Parallel-Weave）——召集多名织手横向并行，一个模板 + N 份材料扇出，按输入顺序聚合成带续跑句柄的 report；**斗巧·竞争织造模式**（Douqiao · Contest-Weave）——多名织手互不相通地独立完成同一任务（`models` 参数可让不同厂商模型各织一匹），判官比对择优，以 N 倍投入换质量上限；**宸枢·统筹织造模式**（Chenshu · Sovereign-Weave）——总枢坐镇规划、分派、监督、汇总，大工程拆成 scope 互不重叠的 mission，worker 在独立分支 worktree 里并行推进，评审过闸后合回主干。见 [docs/multi-agent.md](docs/multi-agent.md)
- **多会话并行**：一个终端跑长任务，另一个终端 `xiaoyu send <会话名> "..."` 递话，对方在下个步骤边界收进上下文；模型自己也会用——直接说"看看还有哪些会话""让 api-1 帮我查一下"，发信前问你一次
- **可平台化**：三张脸（一次性执行 / 嵌入 SDK / `serve`）共用同一套事件流、审批回路、`output_schema` 结构化收尾与边界；宿主把业务动作包成 MCP server 挂到 agent 对象上，审批走宿主自己的 UI——选型与样本见 [docs/platform.md](docs/platform.md)、[examples/ops-console](examples/ops-console/)
- **可嵌入**：独立 Python 包 `xiaoyu-agent-sdk`（按上面的安装命令已装好），提供同步/异步会话、审批、事件流、业务工具与严格结构化结果；见 [SDK 指南](docs/sdk.md) 和 [完整示例](examples/sdk/README.md)。现有 `import xiaoyu` 公开 API 保持兼容，契约见 [docs/embedding.md](docs/embedding.md)；跨语言可用 `--wire` 的 stdio JSON-RPC。
- **可编排**：`xiaoyu serve` 起 HTTP API，n8n / Dify / 自研调度直接驱动（异步提交 + 状态轮询 + 事件游标，需要放行的工具调用挂起等 HTTP 回决定）。OpenAPI schema 由代码生成，贴给 Dify 自定义工具即用——见 [docs/http-api.md](docs/http-api.md)。同一服务还在 `/mcp` 挂着 **agent 级 MCP server**（`xiaoyu` / `xiaoyu_reply` / `xiaoyu_close` 三工具，streamable HTTP），LangChain / LangGraph 经官方 `langchain-mcp-adapters` 即插即用，其它 MCP client 同理——见 [docs/mcp-server.md](docs/mcp-server.md)。**浏览器桥**：浏览器扩展连上同一服务，agent 就能在用户登录态的浏览器里读页 / 点击 / 截图，写类动作走审批——见 [docs/browser-bridge.md](docs/browser-bridge.md)
- **浏览器**：推荐挂 chrome-devtools MCP；内置 `[browser]` 是纯 pip 的兜底，`playwright install chromium` 后即用

## 安全与贡献

- 报告漏洞、支持的版本、给使用者的风险告诫：[SECURITY.md](SECURITY.md)；审批 / 沙箱 / 硬红线的设计：[docs/security.md](docs/security.md)
- 在本仓库里干活的 agent（和人）先读 [AGENTS.md](AGENTS.md)：测试命令、提交纪律、公开 API 冻结面
- 想给 bash 命令加一道模型二审：[examples/hooks/adversary](examples/hooks/adversary/)（PreToolUse 钩子样本，补充层、fail-open）

---

<p align="center"><sub>天羽织造 · 凤凰出品<br>woven by Xiaoyu · a Pholex (凤凰) production</sub></p>
