面向小型 Python 仓库的多智能体 CLI 软件工程助手。系统能够在沙盒仓库中读取文件、修改代码、运行命令、验证测试、生成 diff、记录执行过程，并将成功经验沉淀为可复用技能。
Agentic CLI Workspace 是一个课程项目级 真实环境 CLI 智能体系统，核心目标是展示大模型智能体从“回答问题”走向“真实执行”的工程闭环：
任务输入 -> 仓库沙盒 -> 多智能体协作 -> 工具调用 -> pytest 反馈 -> 代码修复 -> Verifier 硬验证 -> Reporter 生成证据链
它不是只输出建议的聊天机器人，而是一个能够操作本地代码仓库、执行测试并基于硬证据判断任务是否完成的多智能体系统。
| 课程方向 | 项目对应 |
|---|---|
| 软件工程师智能体 | 围绕需求理解、代码修改、测试验证、文档报告生成开展协作 |
| CLI 智能体 | 通过命令行入口与文件系统、终端命令、pytest 等工具交互 |
| 真实环境智能体 | 具备环境操作、流程控制、安全策略、可观测执行轨迹和经验沉淀 |
| 多智能体系统 | RepoScanner、TaskRouter、Engineer、Runner、Verifier、Reviewer、Reporter 等角色分工明确 |
| 能力 | 当前实现 |
|---|---|
| 多智能体协作 | RepoScanner / TaskRouter / ArchitectPlanner / Engineer / Runner / Verifier / Reviewer / Reporter |
| 自适应工作流 | 根据任务复杂度自动选择 Fast Path 或 Project Path |
| 真实环境操作 | 读取文件、写入代码、执行 python -m pytest -q、生成 diff.patch |
| 沙盒隔离 | 每次 run 复制仓库到 artifacts/run_xxx/workdir/，避免污染原始仓库 |
| 硬验证 | Verifier 基于 returncode、pytest 输出、测试文件保护和修改证据做确定性判断 |
| 返工闭环 | Reviewer 根据 Verifier 结果决定 FINISHED 或 RETRY |
| 可观测性 | 生成 events.jsonl、tool_calls.jsonl、metrics.json、command_results.json |
| Replay / Report | 支持 replay 和 report 查看历史运行过程与最终报告 |
| Benchmark | 支持 fast/project/all 分组 benchmark 与 dry-run 预览 |
| 安全机制 | safe / normal / dangerous 安全等级，默认 safe |
| Skill Memory | 成功任务自动沉淀到 memory/skills_memory.json，后续任务可检索复用 |
| CLI 体验 | Rich 面板、Mission Summary、Next Actions、可复制命令 |
RepoScanner -> TaskRouter
├── Fast Path: Engineer -> Runner -> Verifier -> Reviewer -> Reporter
└── Project Path: ArchitectPlanner -> Engineer -> Runner -> Verifier -> Reviewer -> Reporter
| Agent | 职责 | 关键产物 |
|---|---|---|
| RepoScanner | 扫描沙盒仓库结构与关键文件 | repo summary |
| TaskRouter | 判断任务复杂度，选择 fast/project 工作流 | workflow_decision.json |
| ArchitectPlanner | 面向复杂任务生成架构、任务卡和验收标准 | architecture.md、backlog.json |
| Engineer | 阅读源码/测试、修改文件、提交命令队列 | changed files / tool calls |
| Runner | 执行命令并记录结构化结果 | command_results.json、commands.log |
| Verifier | 用硬证据判断任务是否完成 | verification.json、verification_report.md |
| Reviewer | 根据 Verifier 决定返工或结束 | review decision |
| Reporter | 汇总报告、diff、metrics、安全策略和技能记忆 | final_report.md、diff.patch |
Agentic_CLI_Workspace/
├─ src/
│ ├─ cli.py # Typer CLI 入口
│ ├─ graph.py # LangGraph 工作流
│ ├─ nodes/ # 多智能体节点
│ ├─ tools/ # 文件与命令工具
│ ├─ sandbox.py # run 级 workdir 沙盒
│ ├─ security.py # 安全策略与权限等级
│ ├─ observability.py # events/tool_calls/metrics
│ ├─ benchmark.py # 批量评测
│ └─ skill_memory.py # 技能记忆
├─ docs/ # 结项、架构、答辩、演示材料
├─ tests/ # 框架级测试
├─ artifacts/ # 运行产物目录，提交包默认只保留 .gitkeep
├─ memory/ # 技能记忆目录，提交包默认只保留 .gitkeep
├─ workspace/ # demo-setup 默认工作区
├─ .env.example # 环境变量模板，不包含真实密钥
└─ README.md
Windows PowerShell 推荐每个版本目录单独创建 .venv：
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
Copy-Item .env.example .env编辑 .env，填入自己的 API Key：
PROXY_API_KEY=your_api_key
PROXY_BASE_URL=https://new.lemonapi.site/v1
DEFAULT_MODEL=[L]gemini-3-flash-preview-search
FAST_ENGINEER_MODEL=[L]gemini-3-flash-preview-search
PLANNER_MODEL=[L]gemini-3-pro-preview
PROJECT_ENGINEER_MODEL=[L]gemini-3-pro-preview
REVIEWER_MODEL=[L]gemini-3-flash-preview-search
REPORTER_MODEL=[L]gemini-3-flash-preview-search
STREAMING=false
MAX_TOKENS=8192
MAX_RECURSION_LIMIT=30
COMMAND_TIMEOUT_SECONDS=60
AGENTIC_CLI_SECURITY_LEVEL=safe检查环境：
python -m src.cli doctor
python -m pytest -q tests结项前已验证：doctor 全项 PASS，框架测试 63 passed。
python -m src.cli demo-setup bugfix
python -m src.cli run "修复当前 failing tests，不要修改测试，完成后运行 python -m pytest -q。" --security-level safe该 demo 会展示：
- 初始测试失败；
- Engineer 读取测试和源码，定位
remove_done/count_pending逻辑问题； - 修改实现文件而不修改测试；
- Runner 重新执行 pytest；
- Verifier 判定通过；
- Reporter 生成最终报告和 diff。
运行结束后根据终端给出的 Run ID 执行：
python -m src.cli replay run_YYYYMMDD_HHMMSS_xxxxxx
python -m src.cli report run_YYYYMMDD_HHMMSS_xxxxxx预览任务：
python -m src.cli benchmark --dry-run按分组运行：
python -m src.cli benchmark --group fast
python -m src.cli benchmark --group project
python -m src.cli benchmark --group all标准 fast 任务集包括 bugfix、feature、edge case、CLI bugfix、docs generation。Project benchmark 用于验证 Project Path 的架构规划、任务卡和项目级验证能力。
每次 run 会生成：
artifacts/run_xxx/
├─ workdir/
├─ repo_info.json
├─ python_info.json
├─ security_policy.json
├─ task.txt
├─ plan.md
├─ workflow_decision.json
├─ events.jsonl
├─ tool_calls.jsonl
├─ metrics.json
├─ commands.log
├─ command_results.json
├─ verification.json
├─ verification_report.md
├─ diff.patch
└─ final_report.md
这些产物能够证明系统做了什么、为什么失败、如何修复、是否通过测试、改了哪些文件，以及是否触发安全策略。
默认安全等级为 safe：
- 命令执行使用
shell=False； - 只允许受控命令，如
python、pytest、只读git、ls、pwd； - 阻止 shell 控制符，如
&&、;、|、<、>； - 阻止
python -c、直接pip install package、mutating git 命令； - 默认禁止修改
test_*.py、tests/、conftest.py、pytest.ini； - 默认禁止写入
.env、key、secret、token 等敏感文件。
项目已经达到课程项目结项要求：
- 功能完整：能够完成真实 bugfix demo；
- 多智能体设计清晰：各 Agent 分工明确，并通过共享状态和工作流协作；
- 系统质量可验证：环境检查通过、框架测试通过、运行产物完整；
- 创新点明确：自适应工作流、沙盒安全、硬验证、Replay/Benchmark、Skill Memory；
- 答辩材料齐全：
docs/下已整理结项报告、答辩提纲、Q&A、演示脚本和评分映射。