MyCode 是一个使用 Python 实现、面向个人开发者的可扩展终端 Coding Agent。
An extensible terminal coding agent built with Python.
它以启动命令时的当前目录作为工作区，通过 OpenAI-compatible Chat Completions 模型完成代码理解、文件修改、命令执行、会话管理和受控的 SubAgent 协作。这是一个个人项目，按“能力依赖 + 风险边界”逐步实现，不建议未经审查直接用于生产环境。
- Agent Loop 与结构化 Tool Calling
- 工作区内的文件查找、读取、写入和编辑
- 受路径边界和风险分级约束的命令执行
- Permission 与人工确认
- 上下文预算、历史压缩、会话持久化与跨会话记忆
- SubAgent 委派：explorer / tester / reviewer
- 通过 MCP 接入外部工具
- Skill：可复用的任务流程包
- CLI 与 Textual 终端界面
要求：
- Python 3.11 或更高版本
- uv
- 一个支持 OpenAI-compatible Chat Completions 的模型服务及其 API Key
使用 uv 安装：
uv tool install mycode-coding-agent安装后 mycode 可以在任意目录使用。从源码安装见 Development。
MyCode 以启动命令时的当前目录作为 Agent 工作区，所以先进入你想让 Agent 操作的项目：
cd D:\path\to\your-project配置模型连接，这三项必填，取值见 Configuration：
MYCODE_API_KEY=your-api-key
MYCODE_BASE_URL=https://your-provider.example/v1
MYCODE_MODEL=your-chat-completions-model启动：
mycode agent当前 CLI 没有 --workspace PATH 参数，切换工作区需要先进入目标目录再启动。建议只在受信任、并且已经用 Git 管理的项目中运行。
| 命令 | 说明 |
|---|---|
mycode agent |
在当前目录启动 coding agent |
mycode tui |
启动 Textual 终端界面 |
mycode runtime --jsonl |
启动机器可消费的 JSONL runtime；stdout 只输出 JSONL，诊断信息写到 stderr |
mycode --help |
查看命令列表；mycode <子命令> --help 查看子命令帮助 |
mycode agent 的会话选项（三者互斥）：
--new：跳过菜单，直接创建新会话。--continue：跳过菜单，续接当前项目最近使用的会话；没有历史会话时新建。--resume SESSION_ID：跳过菜单，续接指定的未删除会话。已永久删除的会话无法恢复。
输出选项同样互斥：--verbose 显示更完整的运行信息，--debug 显示调试级运行信息。
不指定会话选项时，如果当前项目已有历史会话，CLI 会显示交互式菜单，可以选择历史会话、新建会话、永久删除会话或退出；没有历史会话时直接新建，不显示空菜单。
在 agent 和 tui 的交互会话里可以使用 slash command：/help、/new、/sessions、/resume <session_id>、/context、/compact、/exit（别名 /quit）。
会话和记忆保存在用户目录下的 .mycode，并按工作区路径区分项目，同名目录不会互相覆盖：
%USERPROFILE%\.mycode\projects\<workspace-basename>-<12-char-hash>\sessions\<session-id>\
%USERPROFILE%\.mycode\projects\<workspace-basename>-<12-char-hash>\MEMORY.md
%USERPROFILE%\.mycode\MEMORY.md
模型连接写在 .env 文件中，支持用户级和项目级两级：
用户级（Windows）：%USERPROFILE%\.mycode\.env
项目级：<workspace>\.mycode\.env
逐字段优先级为 process environment > project > user > defaults，空字符串不构成有效覆盖。项目级只需要写要覆盖的字段，其余回退到用户级配置；临时覆盖用进程环境变量。项目根目录的 <workspace>\.env 不会被读取。
Windows PowerShell 首次配置：
$mycodeConfigDir = Join-Path $env:USERPROFILE ".mycode"
$mycodeConfigFile = Join-Path $mycodeConfigDir ".env"
New-Item -ItemType Directory -Path $mycodeConfigDir -Force | Out-Null
if (-not (Test-Path $mycodeConfigFile)) {
Copy-Item .env.example $mycodeConfigFile
}然后编辑该文件。必填三项：MYCODE_API_KEY、MYCODE_BASE_URL、MYCODE_MODEL。缺少任意一项时 MyCode 会拒绝启动并指出缺少的配置。
常用可选项：
MYCODE_COMPACT_MODEL、MYCODE_SUBAGENT_MODEL：Compact 和 SubAgent 使用的模型，留空时继承MYCODE_MODEL。LLM_CONTEXT_WINDOW_TOKENS、LLM_RESERVED_OUTPUT_TOKENS、LLM_CONTEXT_SAFETY_MARGIN_TOKENS、LLM_MEMORY_CONTEXT_TOKENS：上下文预算，需要按模型实际的上下文窗口和输出上限设置。LLM_STREAM_INCLUDE_USAGE：要求兼容的流式模型服务返回 token 用量。LLM_THINKING_ENABLED、LLM_REASONING_EFFORT、LLM_MAX_OUTPUT_TOKENS：可选的推理配置，模型服务不支持时保持留空。
完整字段和注释见 .env.example。
项目级 secret 放在 <workspace>\.mycode\.env，该文件已被 .env 的 Git ignore 规则排除；不要提交真实 API Key 或 token。
MCP 用于把外部工具接入同一个 Agent Loop，支持 stdio 和 streamable_http 两种 transport，配置分用户级和项目级：
用户级：%USERPROFILE%\.mycode\mcp.json
项目级：<workspace>\.mycode\mcp.json
{
"mcpServers": {
"local": {
"transport": "stdio",
"command": "python",
"args": ["D:\\path\\to\\server.py"],
"env": {"TOKEN": "${MCP_LOCAL_TOKEN}"}
},
"remote": {
"transport": "streamable_http",
"url": "https://example.com/mcp",
"headers": {"Authorization": "Bearer ${MCP_REMOTE_TOKEN}"}
}
}
}secret 不写进 mcp.json，而是放在 .mycode\.env 里用 ${ENV_VAR} 引用。用户级配置视为你本人的主动配置；项目级 MCP 会在启动时要求一次信任确认，确认前不会建立连接。MCP 工具注册后仍然走 MyCode 的 JSON Schema 校验、Permission 和确认链，与内置工具一致。
Skill 是可复用的任务流程包，由 SKILL.md 和可选的参考文件、脚本组成，按 builtin -> user -> project 顺序发现，同名时项目级覆盖用户级、用户级覆盖内置。内置 Skill 目前是 database-recovery。
用户级：%USERPROFILE%\.mycode\skills\
项目级：<workspace>\.mycode\skills\
MyCode 能够修改文件和执行命令，使用前请注意：
- 先提交或备份重要修改，并确认当前目录就是目标工作区。
- 路径和命令策略会允许、拒绝或要求人工确认工具调用，但不能替代系统级沙箱。
- 命令执行使用结构化参数、不经过 shell；需要人工确认的操作会明确提示。
- Agent 完成后用
git status和git diff检查实际改动。 - MCP Server、文件和网页内容都按不可信外部输入处理，其中的指令不能覆盖 System Prompt、Permission 规则和运行时控制。
- 不要在源码、测试、提示词或 Git 历史中写入真实密钥。
从源码运行：
git clone https://github.com/mmc-cloud/mycode.git
cd mycode
uv sync
uv run mycode agent把本地 checkout 安装成全局命令：
uv tool install .运行测试：
uv run pytest项目结构：
mycode/ 核心 Agent、CLI/TUI、工具、会话、上下文、MCP、Skill 和 SubAgent 实现
tests/ 核心测试
.env.example 用户级或项目级模型配置模板
pyproject.toml 包信息、依赖、CLI 入口和测试配置
uv.lock 锁定的依赖版本
- 主要验证环境是 Windows + PowerShell；macOS/Linux 尚未充分实际验证，目前不作为受支持平台。
- 需要 Python 3.11 或更高版本。
- 不同 OpenAI-compatible Provider 对流式 usage、thinking 和 reasoning 字段的支持可能存在差异，协议行为不完全一致。
- Agent 可以修改文件和执行命令，建议在 Git 管理的项目中运行并检查 diff；输出和工具决策仍需人工审查。
- MCP 第一版不支持 OAuth、Resources、Prompts、Sampling、热加载或原生 Image/Audio ToolResult。
- 当前以终端交互为主，不包含 IDE 插件或图形界面。
This project is licensed under the MIT License. See LICENSE for details.