# MiniClaudeCode - 轻量级代码 Agent Runtime

**Repository Path**: git_bai/mini-claude-code

## Basic Information

- **Project Name**: MiniClaudeCode - 轻量级代码 Agent Runtime
- **Description**: miniClaudeCode: 一个面向代码仓库的轻量级 AI Agent Runtime，聚焦工具调用、权限控制、上下文管理和自动化开发闭环。正在开发
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-16
- **Last Updated**: 2026-10-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# miniClaudeCode

miniClaudeCode 是一个用 Python 实现的轻量级 AI Coding Agent 工程项目。它不是简单的聊天壳，也不是只包装一次 API 调用，而是围绕真实代码智能体需要的运行时、工具调用、长任务执行、工程验证、Git 闭环和长期记忆做了一套可阅读、可测试、可演示的最小实现。

项目目标是把 Claude Code 类终端编程助手的关键工程链路拆开，用较小代码规模复现核心思想，并在此基础上做工程化增强。

## 项目定位

```text
用户请求
  |
  v
AgentLoop
  |
  v
Tool Runtime
  |
  v
Planner Executor Evaluator Harness
  |
  v
Git Workflow 工程闭环
  |
  v
Memory and Context Engineering
```

当前项目已经形成四个核心工程模块：

| 模块 | 解决的问题 | 产出 |
| --- | --- | --- |
| Tool Runtime | 工具调用如何安全、可观测、可扩展地执行 | 插件式工具发现、schema 校验、权限、diff preview、超时、重试、压缩、tracing |
| Planner Executor Evaluator Harness | 长任务如何拆解、执行、验证和修复 | run artifacts、task plan、evaluator report、final report、repair loop |
| Git Workflow 工程闭环 | 代码改动如何被检查、总结和提交前验证 | worktree inspect、diff summary、test runner、commit message suggestion |
| Memory and Context Engineering | Agent 如何沉淀项目认知并选择上下文 | project memory、file summary、task memory、context builder、context compression |

## 核心亮点

### 1. Tool Runtime

传统教学型 Agent 项目常见做法是把工具硬编码到 registry 里，然后直接执行模型返回的 tool_use。miniClaudeCode 把这一层升级成独立运行时。

| 能力 | 说明 |
| --- | --- |
| 工具自动发现 | 扫描 `miniclaudecode.tools` 包，自动发现所有 `Tool` 子类 |
| 工具名重复检测 | registry 注册时检测重复工具名 |
| JSON Schema 校验 | 执行前校验模型传入参数 |
| 错误类型标准化 | `unknown_tool`、`validation_error`、`permission_denied`、`timeout_error`、`execution_error` 等 |
| 权限检查 | 支持 ask、auto、plan 三种模式 |
| Diff preview | `write_file` 和 `edit_file` 在写入前生成 unified diff |
| 用户确认 | ask 模式下可确认或拒绝写操作 |
| 超时控制 | Runtime 层提供统一超时，bash 工具自身也有 subprocess timeout |
| 重试机制 | 只读工具可配置 retryable |
| 结果压缩 | 长工具输出按 head 和 tail 压缩，避免塞爆上下文 |
| Tracing | 工具调用以 JSONL 事件写入 `.miniclaudecode/traces` |

核心文件：

```text
miniclaudecode/runtime/tool_runtime.py
miniclaudecode/runtime/tool_loader.py
miniclaudecode/runtime/schema_validator.py
miniclaudecode/runtime/compression.py
miniclaudecode/runtime/tracing.py
miniclaudecode/tools/base.py
```

### 2. Planner Executor Evaluator Harness

长任务不能只靠一次 AgentLoop 直接执行。miniClaudeCode 增加了轻量 Harness，把一次需求拆成结构化任务，执行后用确定性检查验证，并在失败时把 evaluator feedback 回传给执行器。

| 能力 | 说明 |
| --- | --- |
| ArtifactStore | 每次 run 创建独立目录 |
| Planner | 生成结构化 plan 和 task markdown |
| Executor | 构造任务 prompt 并调用 AgentLoop 或兼容 runner |
| Evaluator | 运行 `python -m unittest discover`、`python -m compileall`、`git diff --stat` 等确定性检查 |
| Repair loop | 失败后将 evaluator feedback 注入下一轮执行 |
| Final report | 汇总 task、events、tool traces、evaluation checks、repair rounds、Git diff 和测试结果 |
| CLI 接入 | 支持 `--run-harness` 和 `--list-runs` |

运行产物示例：

```text
.miniclaudecode/runs/<run_id>/
  request.md
  spec.md
  plan.json
  events.jsonl
  tasks/
  evaluator_reports/
  traces/
  final_report.md
```

### 3. Git Workflow 工程闭环

代码 Agent 最终必须落到工程交付。miniClaudeCode 增加了 Git Workflow 层，把工作区状态、diff、测试结果和提交信息建议整合成报告。

| 能力 | 说明 |
| --- | --- |
| WorktreeInspector | 读取 branch、changed、staged、untracked、dirty 状态 |
| DiffSummary | 解析 `git diff --numstat`，生成文件级增删统计 |
| TestRunner | 运行测试命令并截断超长输出 |
| CommitMessageGenerator | 根据 diff 和测试结果生成提交信息建议 |
| GitWorkflow | 串联 inspect、diff、test、commit message |
| CLI 接入 | 支持 `--git-summary` 和 `--git-commit-message` |
| Memory 接入 | GitWorkflow report 可转换为 TaskMemory |

### 4. Memory and Context Engineering

Agent 如果每次任务都重新扫描项目，会浪费上下文，也无法复用历史工程判断。miniClaudeCode 增加了文件化长期记忆和上下文选择层。

| 能力 | 说明 |
| --- | --- |
| Memory Records | 定义 `FileSummary`、`ProjectSummary`、`DecisionRecord`、`TaskMemory`、`ContextBundle` |
| MemoryStore | 将记忆写为 Markdown，同时内嵌 JSON 元数据保证结构化读取 |
| ProjectIndex | 扫描 tracked 和未忽略文件，过滤 `.git`、`.env`、虚拟环境和缓存目录 |
| Summarizer | 不依赖 LLM，确定性提取 Python symbol、Markdown heading 和文本预览 |
| ContextBuilder | 根据当前任务关键词选择相关文件摘要、工程决策和历史任务 |
| Context compression | 按字符预算裁剪 task memory、decision 和 file summary |
| CLI 接入 | 支持 memory index、memory context 和 memory list |
| Harness 接入 | Harness 完成后写入 TaskMemory |
| GitWorkflow 接入 | GitWorkflow 分析结果写入 TaskMemory |

运行产物示例：

```text
.miniclaudecode/memory/
  project.md
  files/
  decisions/
  tasks/
  context/
```

## 快速开始

建议使用 Python 3.11 或更新版本。项目依赖以 `pyproject.toml` 为权威来源，`requirements.txt` 保留给习惯使用 `pip install -r requirements.txt` 的环境。

创建虚拟环境：

```bash
python -m venv .venv
```

Windows PowerShell:

```powershell
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

macOS 或 Linux:

```bash
source .venv/bin/activate
python -m pip install -e ".[dev]"
```

只安装运行依赖：

```bash
python -m pip install -e .
```

配置 Anthropic API Key：

```powershell
$env:ANTHROPIC_API_KEY="你的 API Key"
```

macOS 或 Linux:

```bash
export ANTHROPIC_API_KEY="你的 API Key"
```

## CLI 使用

### 基础 Agent

启动交互式聊天：

```bash
python -m miniclaudecode chat
```

一次性执行 prompt：

```bash
python -m miniclaudecode run "帮我查看当前目录有哪些 Python 文件"
```

查看当前可用工具：

```bash
python -m miniclaudecode tools
```

检查配置、工具、workspace root、harness runs 目录和 API Key 状态：

```bash
python -m miniclaudecode doctor
```

如果 `ANTHROPIC_API_KEY` 缺失，workspace root 不存在、不是目录、不可读写，或 harness runs 目录无法创建/写入，`doctor` 会输出修复动作并返回非零退出码，适合放进 CI 或上线前检查。

兼容旧的 prompt 写法：

```bash
python -m miniclaudecode "帮我查看当前目录有哪些 Python 文件"
```

指定模型、权限模式和最大循环轮数：

```bash
python -m miniclaudecode --model claude-sonnet-4-20250514 --mode ask --max-turns 30 chat
```

指定 JSON 或 TOML 配置文件（优先级：默认值 < 配置文件 < 环境变量 < CLI 参数）：

```bash
python -m miniclaudecode --config miniclaudecode.config.toml "查看项目状态"
```

可从 `miniclaudecode.config.toml.example` 复制一份配置。模型价格字段是可选的；配置后，每次 Harness run 会把 token、耗时、stop reason 和本地估算成本写入 `traces/model_calls.jsonl`，但不会保存 prompt、模型文本或 API Key。

交互模式命令：

| 命令 | 作用 |
| --- | --- |
| `/tools` | 查看当前注册工具 |
| `/mode` | 查看当前权限模式 |
| `/mode ask` | 切换到 ask 模式 |
| `/mode auto` | 切换到 auto 模式 |
| `/mode plan` | 切换到 plan 模式 |
| `/help` | 查看帮助 |
| `/quit` | 退出 |

### Harness

列出历史 run：

```bash
python -m miniclaudecode --list-runs
```

运行长任务 Harness：

```bash
python -m miniclaudecode --run-harness "实现一个新功能"
```

每个 Harness run 都会持久化 `run_state.json` 和状态迁移事件。进程在任务执行或评估时中断后，可以从首个未完成任务恢复，不会重跑已通过的任务：

```bash
python -m miniclaudecode --resume <run_id>
```

指定多个任务：

```bash
python -m miniclaudecode --run-harness --harness-task "实现核心逻辑" --harness-task "补充测试" "实现一个新功能"
```

Harness evaluator 通过可配置的 grader registry 执行确定性验收。默认启用 `unit_tests`、`py_compile` 和 `git_diff_stat`；可以在配置文件的 `harness.graders` 或环境变量 `MINICLAUDECODE_HARNESS_GRADERS` 中选择启用项。任务是否通过只取决于实际 grader 结果，不再根据标题或验收描述中是否出现“test/测试”关键词判断。

每个 `TaskSpec` 除文字验收标准外，还可以声明独立的 `test_commands`。命令使用参数数组表示，支持 `{python}` 占位符；执行时不经过 shell。任务计划、任务 Markdown、Agent prompt、evaluator report 和恢复状态都会保留这份契约：

```python
task = TaskSpec(
    id="task-001",
    title="修复配置优先级",
    acceptance=["环境变量覆盖配置文件", "默认行为保持不变"],
    test_commands=[
        ["{python}", "-m", "unittest", "tests.test_config.TestLoadConfig"],
    ],
)
```

全局 grader 负责仓库级基础质量门禁，任务专属命令负责验证当前任务的精确验收范围；任一检查失败都会进入 repair feedback。没有声明 `test_commands` 的旧任务保持兼容。

### Git Workflow

输出 Git 工程报告：

```bash
python -m miniclaudecode --git-summary
```

跳过测试，只生成 Git 报告：

```bash
python -m miniclaudecode --git-summary --skip-git-tests
```

只输出提交信息建议：

```bash
python -m miniclaudecode --git-commit-message --skip-git-tests
```

### Offline Evals

校验并列出本地评测案例：

```bash
python -m miniclaudecode --list-evals
```

默认只展示用于日常调试的 development 集。held-out 集必须显式选择；审计完整目录时可使用 `all`：

```bash
python -m miniclaudecode --list-evals --eval-split held-out
python -m miniclaudecode --list-evals --eval-split all
python -m miniclaudecode --mode auto --run-eval block-path-traversal --eval-split held-out
```

在一次性临时工作区运行单个案例（真实 Agent 执行需要 API Key，建议使用自动授权模式）：

```bash
python -m miniclaudecode --mode auto --run-eval fix-calculator-add
```

对同一案例运行多个相互隔离的 trial：

```bash
python -m miniclaudecode --mode auto --run-eval fix-calculator-add --trials 3
```

批量模式会为每次 trial 创建新的 Agent、临时 Git 仓库和产物目录。单次基础设施错误不会阻断剩余 trial；批次级 `trials_summary.json` 会记录稳定的 `trial-001` 等标识、每次状态和结果路径，并分别汇总通过、任务失败与基础设施错误数量。

`trials_summary.json` 同时提供标准化指标：经验 `pass@1`、无放回组合估计 `pass@k = 1 - C(n-c,k)/C(n,k)`、严格连续成功指标 `pass^k = C(c,k)/C(n,k)`，以及 token、估算成本、trial 耗时、模型/工具调用数的 total、mean、P50、P95。`pass@1` 和各类 trial 失败率附带 Wilson 95% 置信区间，避免小样本点估计造成过度解读。失败被拆分为 Agent 失败（候选执行异常或未通过验收）、grader 失败（评测流程自身异常）和基础设施失败（工作区准备等系统问题）；三类失败都会保守计入未通过。grader 断言未通过率单独统计，不与 grader 自身异常混淆。未配置模型价格时，成本标记为不可用而不是错误地记为 0。

每个批次还会在执行 trial 之前写入 `experiment_manifest.json`，固化 Git commit、分支与 dirty 状态、miniClaudeCode/模型版本、脱敏后的规范化配置及其 SHA-256、Python/操作系统信息，以及 EvalCase 哈希、schema 和资源预算。临时工作区路径会替换为稳定占位符，API Key 不进入快照，因此同一配置可跨机器比较且不会泄露凭据。

runner 会分别复制只读基线和候选工作区，并把候选初始化为带基线提交的临时 Git 仓库，Agent 只能操作候选副本；随后自动计算内容级变更、运行全部 grader，并把版本化结果原子写入 `.miniclaudecode/evals/<case_id>/<batch_id>/<trial_id>/eval_result.json`。临时仓库在成功或异常后都会清理，fixture 不会被修改；执行器异常也会持久化为 `infrastructure_error`，保留可审计的失败证据。

每个 trial 还会保存 `transcript.jsonl`、`tool_trajectory.jsonl`、`candidate.diff`、`grader_results.json` 和原始 trace。`artifacts.json` 为全部产物记录相对路径、媒体类型、字节数和 SHA-256，可用于 CI 归档完整性校验以及后续实验回放。

CI 会在每个 development 案例上运行一次确定性的 no-op 校准，不调用模型/API，并要求 grader 能拒绝未修复候选、识别已知失败测试且保留通过中的回归测试。批次摘要、实验 manifest、trial 结果和 grader 证据会作为 CI artifact 保存 14 天。需要真实 Claude API smoke eval 时，在 GitHub Actions 手动运行 `CI`、勾选 `run_claude_api_smoke`，并配置 `ANTHROPIC_API_KEY` repository secret；常规 push/PR 不会调用外部模型。

`evals/cases/*.json` 使用版本化 `EvalCase` 协议，明确任务、fixture、成功标准、grader 声明、资源预算和标签。fixture 只能引用 `evals/fixtures/` 下的相对目录，目录穿越、未知字段、重复 ID 和非法预算会在加载阶段失败。当前 10 个本地案例构成首批能力矩阵：

| 能力维度 | 代表案例 |
| --- | --- |
| 搜索定位 | `fix-tax-rounding`、`discover-nested-tests` |
| 修改与回归 | `fix-calculator-add`、`preserve-order-deduplication` |
| 测试工程 | `discover-nested-tests` |
| 失败恢复 | `recover-malformed-records` |
| 安全边界 | `block-path-traversal`、`redact-nested-secrets` |
| 上下文理解 | `fix-config-precedence`、`fix-cache-key-context` |
| 跨文件实现 | `implement-capped-retries` |

每个 fixture 的完整测试套件在基线状态下都可重复失败，同时至少保留一个初始通过的回归测试；grader 再约束预期修改文件和禁止修改测试，从而减少“删测试”或无关重写带来的虚假通过。

任务目录按 7 个 development 和 3 个 held-out 案例拆分。`split` 是版本化 EvalCase 协议的一部分，并贯穿单次 `eval_result.json`、批次 `trials_summary.json` 与 `experiment_manifest.json`；CLI 默认只访问 development，避免日常策略调试无意间消费最终评估集。旧版清单未声明 split 时向后兼容为 development。

对比同一 case/split 的两个批次时，直接传入它们的汇总文件。系统会校验 case 身份和可用的 EvalCase 指纹，计算核心通过率、token、成本、耗时、工具调用和错误率的变化，并区分改善、回退、持平与不可用；模型或配置不同会作为解释性提示保留。缺少成本等指标时显示 `unavailable`，不会按零参与判断。

```bash
python -m miniclaudecode --compare-evals \
  .miniclaudecode/evals/fix-calculator-add/baseline/trials_summary.json \
  .miniclaudecode/evals/fix-calculator-add/experiment/trials_summary.json \
  --comparison-output reports/calculator-v2
```

命令会生成 `reports/calculator-v2.json` 和 `reports/calculator-v2.md`。`outcome` 汇总可用指标的方向：`improved`、`regressed`、`mixed`、`unchanged` 或 `insufficient_data`；相对变化在 baseline 为零时标记为不可用。

内置确定性 grader：

- `no_op`：对基线与候选工作区生成内容指纹，排除缓存等运行产物后必须存在实质变化。
- `fail_to_pass`：基线命令失败，候选修改后必须通过。
- `pass_to_pass`：基线原本通过的回归检查，在候选修改后仍须通过。
- `expected_changes`：检查必改文件以及允许修改的文件边界。
- `forbidden_changes`：用路径模式阻止测试、Git 元数据等受保护区域被修改。

命令 grader 使用参数数组执行，不经过 shell，并受 EvalCase 超时预算约束；输出会截断后写入版本化 `EvalGradeReport`。no-op grader 基于文件路径与 SHA-256 内容摘要比较工作区，默认忽略 `.git`、`__pycache__`、字节码及质量工具缓存，避免运行产物制造虚假改动。

### Memory

刷新项目 memory：

```bash
python -m miniclaudecode --memory-index
```

为当前任务构建上下文：

```bash
python -m miniclaudecode --memory-context "优化 ToolRuntime 的错误分类"
```

查看 memory 记录数量：

```bash
python -m miniclaudecode --list-memory
```

推荐演示流程：

```bash
python -m miniclaudecode --memory-index
python -m miniclaudecode --memory-context "优化 ToolRuntime 的错误分类"
python -m miniclaudecode --git-summary --skip-git-tests
python -m miniclaudecode --list-memory
```

## 内置工具

| 工具名 | 作用 |
| --- | --- |
| `bash` | 执行 shell 命令，带危险命令拦截和超时 |
| `read_file` | 读取文本文件并返回带行号内容 |
| `write_file` | 写入文件，支持 diff preview |
| `edit_file` | 精确字符串替换，支持 diff preview |
| `glob` | 按 glob 规则查找文件 |
| `grep` | 搜索文件内容，优先使用 ripgrep |

只读工具具备 retryable 和 read_only 标识，写入和 bash 默认不自动重试。

## 权限模式

| 模式 | 行为 |
| --- | --- |
| ask | 默认模式。危险操作和写操作需要确认 |
| auto | 自动执行通过工具自检的操作 |
| plan | 只读模式，阻止 bash、write_file、edit_file |

ask 模式的交互式确认会展示工具名、目标路径或命令、风险说明和 diff 摘要。用户可以选择：

```text
o / once    允许本次执行
a / always  对同一命令或同一工具目标永久允许
d / deny    拒绝执行
```

权限检查由工具自检、工作区边界和全局权限模式共同决定。

## 配置

配置分为 `ModelConfig`、`ToolRuntimeConfig`、`SafetyConfig` 和 `HarnessConfig`。

加载优先级：

```text
默认值 < JSON 配置文件 < 环境变量 < CLI 参数
```

示例配置文件：

```json
{
  "model": {
    "model": "claude-sonnet-4-20250514",
    "max_turns": 30,
    "max_context_messages": 100
  },
  "tool_runtime": {
    "max_output_chars": 50000,
    "max_tool_result_chars": 12000,
    "tool_result_head_chars": 8000,
    "tool_result_tail_chars": 4000,
    "enabled_tools": [],
    "disabled_tools": []
  },
  "safety": {
    "workspace_root": ".",
    "permission_mode": "ask",
    "allowed_commands": ["ls", "cat", "git status", "git diff", "python3"],
    "denied_patterns": ["rm -rf /", "git reset --hard", "git push --force"]
  },
  "harness": {
    "runs_dir": ".miniclaudecode/runs",
    "max_repair_rounds": 1,
    "graders": ["unit_tests", "py_compile", "git_diff_stat"]
  }
}
```

常用环境变量：

| 环境变量 | 对应配置 |
| --- | --- |
| MINICLAUDECODE_MODEL | model.model |
| MINICLAUDECODE_MAX_TURNS | model.max_turns |
| MINICLAUDECODE_WORKSPACE_ROOT | safety.workspace_root |
| MINICLAUDECODE_PERMISSION_MODE | safety.permission_mode |
| MINICLAUDECODE_ALLOWED_COMMANDS | safety.allowed_commands，逗号分隔 |
| MINICLAUDECODE_DENIED_PATTERNS | safety.denied_patterns，逗号分隔 |
| MINICLAUDECODE_ENABLED_TOOLS | tool_runtime.enabled_tools，逗号分隔 |
| MINICLAUDECODE_DISABLED_TOOLS | tool_runtime.disabled_tools，逗号分隔 |
| MINICLAUDECODE_HARNESS_RUNS_DIR | harness.runs_dir |
| MINICLAUDECODE_MAX_REPAIR_ROUNDS | harness.max_repair_rounds |
| MINICLAUDECODE_HARNESS_GRADERS | harness.graders，逗号分隔 |

## 目录结构

```text
miniclaudecode/
  agent_loop.py
  cli.py
  config.py
  context.py
  errors.py
  permissions.py
  workspace.py
  runtime/
  tools/
  harness/
  git_workflow/
  memory/
tests/
docs/
```

重要运行时目录：

```text
.miniclaudecode/
  traces/
  runs/
  memory/
```

## 测试与工程命令

项目使用 unittest，并通过 Makefile 统一本地工程命令。

首次开发建议安装运行依赖和 dev 工具：

```bash
make install
```

常用命令：

```bash
make test
make e2e
make coverage
make lint
make format
make typecheck
make build
make check
```

直接运行 unittest：

```bash
python -m unittest discover
```

测试覆盖范围：

| 测试范围 | 内容 |
| --- | --- |
| tools | bash、file read、file write、edit、glob、grep |
| runtime | discovery、schema validation、timeout、retry、compression、tracing |
| harness | artifacts、planner、executor、evaluator、task harness、final report |
| git workflow | worktree、diff summary、test runner、commit message、workflow |
| memory | records、store、project index、summarizer、context builder |
| cli | product commands、harness、git workflow、memory 命令 |
| e2e | fixture repo 端到端 agent task |

## 开发流程

本项目代码变更建议遵守以下流程：

1. 从 master 新建功能分支，分支名使用 `feature/功能名字`。
2. 在功能分支完成修改，并运行 `make check` 或至少运行 `python -m unittest discover`。
3. 检查通过后提交代码。
4. 合并回 master。
5. 将 master 推送到远程仓库。

## 面试讲法

可以这样介绍项目：

```text
miniClaudeCode 是我实现的轻量级 AI Coding Agent Runtime。它从一个基础 AgentLoop 出发，逐步补齐真实代码智能体需要的四个工程层：工具运行时、长任务 Harness、Git Workflow 工程闭环、长期记忆与上下文压缩。项目重点不是简单调 API，而是围绕工具调用安全性、可观测性、任务拆解验证、代码交付闭环和上下文复用做工程化设计。
```

简历表达可以写：

```text
设计并实现轻量级 AI Coding Agent Runtime，支持插件式工具发现、JSON Schema 校验、权限控制、diff preview、工具 tracing、长任务 Planner Executor Evaluator Harness、Git Workflow 工程闭环以及文件化长期记忆与上下文压缩，提升 Agent 在多轮代码任务中的安全性、可观测性和上下文复用能力。
```

## 和普通 Agent Demo 的区别

| 普通 Demo | miniClaudeCode |
| --- | --- |
| 一次 API 调用加工具执行 | 多轮 AgentLoop 和 ToolRuntime |
| 工具硬编码 | 工具自动发现和 schema 校验 |
| 缺少验证 | Harness 和 GitWorkflow 做确定性检查 |
| 没有产物 | run artifacts、events、traces、final report |
| 没有上下文沉淀 | MemoryStore、ProjectIndex、ContextBuilder |
| 难以解释工程取舍 | 每一块都有文档、测试和可演示命令 |

## 后续可优化方向

当前项目已经具备完整展示闭环，后续更适合做成熟度打磨：

1. 增加 `.miniclaudecode/config.toml`，把上下文长度、测试命令、trace 开关等配置化。
2. 为 memory 命令增加 `--max-context-chars` 和 `--output`。
3. 为 `--git-summary` 增加是否写入 memory 的开关。
4. 增加端到端测试，覆盖 memory-index、memory-context、git-summary、list-memory 的完整链路。
5. 增加一份总架构图文档，专门服务面试讲解。

## 注意事项

1. `bash` 工具会在本地执行命令，只适合受控环境。
2. `auto` 模式会自动执行通过工具自检的操作，使用前应确认当前工作区安全。
3. `.miniclaudecode/` 是运行时产物目录，包含 traces、runs 和 memory。
4. Memory 层只记录摘要和元信息，不保存完整大文件内容。
5. 当前项目提供 `pyproject.toml`，可通过可编辑安装获得 `miniclaudecode` 命令。