一个以 harness 为中心的 Python AI coding agent

Double-layer agent loop · Tool harness · Context compression · Memory · Task runtime · Skills / MCP / Worktree

XxCode 不是把“对话 + 执行”塞进一个黑盒循环里的聊天机器人。它把 agent 的关键能力拆成清晰的 runtime 边界：对话编排、工具调度、权限判定、任务隔离、上下文压缩和记忆回收，各自独立、各自可测。

用户输入
  -> CLI 解析配置和参数
  -> Memory bootstrap / recall 准备
  -> Context pipeline 压缩上下文
  -> QueryEngine 处理会话状态与 turn
  -> CoreExecutionEngine 进入 tool loop
  -> Tool harness 调度工具
  -> Permission pipeline 判定是否允许执行
  -> Task runtime 处理子任务、worker 和通知
  -> 返回结果并进入下一轮

pip install -e .

# Required
$env:XXCODE_API_KEY="your_api_key"
$env:XXCODE_API_BASE_URL="your_base_url"

# Optional: defaults to deepseek-v4-pro
$env:XXCODE_API_MODEL="deepseek-v4-pro"

xxcode

模型配置：

• 默认模型是 deepseek-v4-pro
• 可用环境变量 XXCODE_API_MODEL 覆盖
• 兼容 ANTHROPIC_MODEL 作为回退变量
• 也可以用 --model 按单次会话覆盖
• 代码当前支持 claude-*、deepseek-*、gpt-*、o1、o3、o4

例如：

xxcode --model claude-sonnet-4-6
xxcode --model gpt-4o

单次执行：

xxcode --model deepseek-v4-pro -p "帮我分析当前仓库里的测试结构"

常用参数：

• --model：覆盖默认模型
• --cwd：指定工作目录
• --resume：恢复已有会话
• --list：列出已保存会话
• --bare：关闭 auto-memory 等持久特性
• --yolo：跳过权限确认
• --ui-backend：切换终端 UI 后端
• --verbose：开启调试日志
• --max-tokens：限制单轮输出 tokens

使用下面这些命令来运行 benchmark 测试、生成报告，并将当前版本与 baseline profile 进行对比。

仅运行 benchmark 测试：

python -m pytest tests/benchmark -q

仅生成 benchmark 报告：

python scripts/run_unified_eval_report.py

运行完整 benchmark 套件：

python scripts/run_benchmark_suite.py

使用显式指定的报告目录和工作目录来运行完整套件：

python scripts/run_benchmark_suite.py --output-dir .tmp/benchmark-reports --work-dir .tmp/unified-eval-run

与 baseline profile 进行对比：

python scripts/run_benchmark_suite.py --baseline-profile memory_off
python scripts/run_benchmark_suite.py --baseline-profile context_off
python scripts/run_benchmark_suite.py --baseline-profile security_relaxed

• 想研究 agent 内核、执行链路和 runtime 设计的人。
• 想做二次开发，扩展 tool、memory、task 或多 Agent 能力的人。
• 想直接看一个 harness-first AI coding agent 是怎么落地的人。

后续会继续补充更系统的文档讲解，重点会覆盖 memory、multi-agent、tool harness、权限链路和上下文工程这些部分。

当前已经补充的文档：

• docs/agent-loop-query-engine-and-loop-explained.md：从 QueryEngine 入口到 CoreExecutionEngine 内层 tool loop，按主执行路径拆解 XxCode 的核心 agent loop。
• docs/context-engineering-explained.md：解释每轮模型调用前上下文如何被注入、压缩、投影、标准化和缓存标记，重点覆盖 ContextPipeline、L1-L4 压缩和 _build_messages()。
• docs/memory-explained.md：解释 memory 如何作为隐式用户消息进入上下文、如何通过双通道召回保持广度与深度，以及它怎样在后台 extraction 中持续沉淀。
• docs/multi-agent-explained.md：解释 multi-agent runtime 如何派生子 agent、编排 worker、约束权限和工具，并用 scope、通知与 worktree 管住协作边界。

如果你想继续往下看，建议从这些入口开始：

1. docs/agent-loop-query-engine-and-loop-explained.md
2. docs/context-engineering-explained.md
3. docs/memory-explained.md
4. docs/multi-agent-explained.md
5. src/xxcode/agent/loop.py
6. src/xxcode/context/pipeline.py
7. src/xxcode/agent/task_runtime.py
8. src/xxcode/agent/tools_executor.py
9. src/xxcode/tools/agent/tool.py
10. src/xxcode/tools/BashTool/permissions.py