围绕结构化事件流、路径安全、工具审批、审计脱敏、上下文压缩和 REPL 会话管理构建的可测试 Agent 运行骨架。零配置即可运行。

• Python 3.12 或更高
• uv（推荐）或 pip

git clone https://github.com/your-org/xcode.git
cd xcode
uv pip install -e .

以 editable 模式安装到当前项目虚拟环境，源码修改即时生效。

uv tool install --python 3.12 <path-to-xcode>

安装后 xcode 成为系统级 CLI 命令，任意目录下均可调用。升级：

uv tool upgrade xcode --no-cache

uv pip install -e ".[dev]"

开发依赖包括：ruff（格式化/lint）、pyright（类型检查）、pytest（测试框架）。

使用 PyInstaller 将 xcode 打包为免 Python 环境的可执行文件：

# 安装打包依赖
uv pip install -e ".[pack]"

# 打包（onedir 模式，启动快、更新方便）
uv run pyinstaller --onedir --name xcode --paths src src/xcode/__main__.py

# 产出在 dist/xcode/
# 直接运行（Windows）：
.\dist\xcode\xcode.exe --help
# 或（Linux/macOS）：
./dist/xcode/xcode --help

onedir 模式下，依赖层不变时只需重新打包主 exe，_internal\ 目录可复用。

from pathlib import Path
from xcode.harness.app import build_app

app = build_app(project_root=Path.cwd())

answer = app.ask("列出当前目录所有 Python 文件。")
print(answer)

应用配置通过 build_app() 参数、配置文件或环境变量注入。详细配置见 CONFIG.md。

# 直接提问（单轮，自动退出）
xcode "列出当前目录所有 Python 文件。"

# REPL 模式（多轮对话，支持 /slash 命令）
xcode

# 自定义配置
xcode --config .local/settings.json

• 结构化 Agent 循环 — StructuredAgent 消费 provider 流式事件，统一处理 text、reasoning、tool_use、tool_result 和 final answer。
• 核心工具闭环 — 默认提供文件读写编辑、词法搜索和受控 bash。edit_file 依赖 read-before-edit 指纹校验。
• 工具并发分区 — 只读且并发安全的工具并行执行；写操作、高风险命令保持串行。
• 权限与审计 — PermissionEngine 统一执行工具权限判定、HITL 审批和输出脱敏；JsonlAuditLogger 记录审计日志。
• 上下文压缩与恢复 — LayeredCompactor 裁剪过期读取、大输出和旧工具结果，支持压缩后重建文件指纹。
• REPL 会话管理 — 丰富的 /slash 命令体系，支持 plan/build/act、会话分支、回退、模型切换、session transcript 落盘。
• Subagent 委托 — delegate_task 单入口委派子任务，实时流式展示子 agent 进度；支持正式的 worktree 隔离。
• MCP 协议 — 基于官方 Python SDK 连接本地 stdio server，自动发现 .local/mcp_config.json 并注册 mcp__{server}__{tool} 动态工具。
• 实验能力 — 可显式启用 tasks、mailbox 和 progress 断点续传；默认全部关闭。

每轮会按用户问题检索项目根 MEMORY.md 与用户级 ~/.xcode/memory/MEMORY.md，将最多 3 条匹配记录注入 <memory> 上下文。search_memory 是只读、低风险工具。

配置发现栈（优先级从低到高）：

~/.xcode/settings.json          ← 全局默认
     ↓
xcode.config.json               ← 项目级
     ↓
.local/settings.json            ← 本地覆盖
     ↓
环境变量                          ← 最高优先级

所有字段默认值及完整参考见 CONFIG.md。

四层架构，自底向上：

运行路径：main.py → build_app() → StructuredAgent → Agent loop → provider stream → tool execution。

uv run pytest src/xcode/tests -q --tb=short

# 列出可用 eval 套件
uv run python -m xcode.evals.cli --list-suites

# 运行 pipeline 套件
uv run python -m xcode.evals.cli --suite pipeline

# 运行 tool-policy 套件
uv run python -m xcode.evals.cli --suite tool-policy

# 运行真实模型 eval（需要配置 API key）
uv run python -m xcode.evals.cli --real --suite coding-fixture --trials 3

# 基准测试
uv run python -m xcode.evals.cli --list-benchmarks
uv run python -m xcode.evals.cli --real --benchmark evalplus-humaneval --benchmark-path <url> --trials 1

更多说明见 docs/evaluation-guide.md。

uv run ruff check src/ --fix
uv run ruff format src/
uv run pyright src/

• Python 3.12+，完整类型注解
• ruff 格式化（行宽 88），零 # noqa
• 纯函数优先，职责分离（IO / 计算 / 展示）
• 异常捕获明确具体类型，禁止 bare except:

详细规范见 AGENTS.md。

MIT © 2026 Xcode Contributors