小羽 · Xiaoyu

Zhinu Coding Agent | Token Weaver of the Universe
Weaving code, connecting dots, and showing you the best harness architecture.

一个自研的 harness coding agent：
终端里可交互、可无人值守，也可作为库嵌进您自己的程序，支持多会话并行。
依赖极简，适配 Windows / macOS / Linux 全平台。

命名两层：织女 Zhinu 是织坊里的一群 Weaver，小羽 Xiaoyu 是其中一员——harness 是她织机上的提综装置，梭子带着 token 当纬线穿行。
小羽既是织手（Agent），也带着自己的织机（Platform）：自己能织，也能让你把自己的产品架在她的织机上织。

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

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

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

安装

pip install "xiaoyu-agent[tui]"        # [tui]：补全 / 历史 / 粘贴折叠 / 贴图 / diff 高亮
pip install "xiaoyu-agent[tui,serve]"  # 还要 HTTP API（n8n / Dify 编排）就带上 [serve]
xiaoyu doctor                          # 体检：凭据有无 / 沙箱 / 磁盘 / MCP 配置（--json 给脚本，任一 FAIL 退出码 1）
xiaoyu update                          # 升级（已装 serve 时自动一并升级）
xiaoyu uninstall                       # 卸载；--purge 连配置目录一起删

配置

xiaoyu config             # 交互向导
xiaoyu config --show      # 看生效配置与来源（key 永不回显）

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

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

DEEPSEEK_API_KEY=<your-key>

内置直连 deepseek / moonshot / qwen / zhipu / anthropic / gemini / openai / xai，键名一律用厂商原生名。或者走 OpenAI 兼容网关：

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

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

用

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 -s nightly "跑一下回归"                # 命名会话：同名接着聊，脚本反复调用用它

xiaoyu sessions                         # 列出本机会话
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

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

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

模式：放手程度你定

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

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 联网
• 后台任务：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 的跨客户端 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
• 多会话并行：一个终端跑长任务，另一个终端 xiaoyu send <会话名> "..." 递话，对方在下个步骤边界收进上下文；模型自己也会用——直接说"看看还有哪些会话""让 api-1 帮我查一下"，发信前问你一次
• 可平台化：三张脸（一次性执行 / 嵌入 SDK / serve）共用同一套事件流、审批回路、output_schema 结构化收尾与边界；宿主把业务动作包成 MCP server 挂到 agent 对象上，审批走宿主自己的 UI——选型与样本见 docs/platform.md、examples/ops-console
• 可嵌入：import xiaoyu 顶层导出即公开 API（Agent / AsyncAgent / Allow / Deny / 事件类型……，按 semver 维护、破坏性变更走弃用期），把 agent 当执行引擎嵌进你自己的进程（异步审批、事件流、会话复用）；跨语言用 --wire 的 stdio JSON-RPC——契约与示例见 docs/embedding.md
• 可编排：xiaoyu serve 起 HTTP API，n8n / Dify / 自研调度直接驱动（异步提交 + 状态轮询 + 事件游标，需要放行的工具调用挂起等 HTTP 回决定）。OpenAPI schema 由代码生成，贴给 Dify 自定义工具即用——见 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。浏览器桥：浏览器扩展连上同一服务，agent 就能在用户登录态的浏览器里读页 / 点击 / 截图，写类动作走审批——见 docs/browser-bridge.md
• 浏览器：推荐挂 chrome-devtools MCP；内置 [browser] 是纯 pip 的兜底，playwright install chromium 后即用

_{天羽织造 · 凤凰出品
woven by Xiaoyu · a Pholex (凤凰) production}