# MiniCode

**Repository Path**: zj360202/mini-code

## Basic Information

- **Project Name**: MiniCode
- **Description**: 提升自动编码完成率的AI项目
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-10-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCode

MiniCode 是一个面向本地代码仓库的 Agent Coding Workbench。它让用户在浏览器中选择工作空间、提出需求，由模型通过受控工具读取、修改和验证代码；用户可以实时查看执行过程、审批高风险操作，并在需要时继续或恢复任务。

## 项目功能

- 本地开发空间：管理多个项目、会话和历史提问，查看文件变更与 unified diff。
- Agent 执行：支持 Single Agent 和 Multi Agent；Multi Agent 负责 Todo 编排、子 Agent 分派、依赖推进、证据收集和最终汇总，统一使用 `multi_agent` 作为执行标识。子 Agent 可以是 Single Agent 或其他 Multi Agent，未匹配时回退默认 Single Agent。
- 受控工具：统一提供文件读取、搜索、写入、补丁、命令、测试、Git 诊断、运行时探测及 A 股/指数/ETF 行情、K 线、交易日历、公司概况、估值、财务摘要、概念板块、资金流、研报和财经快讯查询能力。
- 权限与边界：以 workspace 为边界，支持只读、询问和授权模式；写入与命令执行可等待人工确认。
- 可观测性：记录 `req_id`、`execution_id`、`trace_id`、Turn、工具结果和执行状态，前端提供执行日志与历史查询。
- 稳定执行：支持 SSE 实时事件、SQLite 持久化、执行恢复、外部动作核对、失败原因展示和批量测试。
- 能力管理：在能力空间统一管理 Tools、Skills、MCP 和推荐能力组合；在智能体配置中可以组合使用。
- 问答式 Skill 导入：可在开发空间输入“导入 Skill + HTTPS URL”，支持 GitHub 仓库/文件/目录、Raw `SKILL.md`、JSON manifest 和 ZIP；系统先冻结内容并生成一次性确认令牌，确认后才写入。
- 问答式 MCP 接入：可提交 MCP Market 说明页、GitHub 仓库或标准 manifest；MCP Market 触发 Vercel challenge 时，Windows 会在受资源约束的 Job Object 中使用无头 Edge 读取官方页面。系统以 Market 页面为来源，只把页面明确声明的仓库作为补充资料，不按名称搜索或猜测替代来源；仅解析标准 `mcpServers` JSON，不执行 README 的安装说明。确认后才运行预览中展示的 Server 命令并执行 `initialize` 和 `tools/list`，失败按本次导入凭据回滚。
- 扩展命令：提供与 Codex 的 MCP / Skill 扩展定位相似的 `python -m minicode mcp ...`、`python -m minicode skill ...` 命令，可添加本地 MCP、远程 HTTP MCP、本地 Skill 或先预览再确认导入 HTTPS 来源。
- 项目开发模式：支持先生成项目设计、用户确认，再进入长期开发、验证和最终验收流程。

## 快速启动

安装项目依赖（金融数据工具依赖 `AKShare` 与 `BaoStock`）后启动：

```powershell
python -m pip install -r requirements.txt
```

在项目根目录执行：

```powershell
python -m minicode.server
```

也可以指定工作空间、端口和数据目录：

```powershell
python -m minicode.server --workspace D:\path\to\project --port 8765 --data-dir D:\path\to\minicode-data
```

Windows 如果 `python` 不在 PATH 中，可以使用本机 Python 解释器：

```powershell
D:\software\anaconda3\python.exe -m minicode.server --workspace D:\path\to\project
```

启动后访问 `http://127.0.0.1:8765`。开发空间和系统设置已经拆分：开发空间负责项目与对话，设置页面负责模型、供应商和空间显示配置，可通过页面右上角“设置”进入。

默认数据目录为用户级 `.minicode` 目录。API Key 只保存在本机配置文件，页面和接口返回脱敏后的信息。

## MCP 与 Skill 扩展

MiniCode 的 MCP / Skill 添加能力与 Codex 的扩展功能定位相似，但采用 MiniCode 自己的命令与受控导入流程。常用示例：

```powershell
python -m minicode mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem D:\workspace
python -m minicode mcp add-url company-data https://example.com/mcp
python -m minicode skill add D:\skills\review
python -m minicode skill import https://github.com/owner/skills/tree/main/review --confirm
```

完整命令、预览确认机制与安全边界见 [扩展命令说明](docs/CAPABILITY_CLI.md)。

## 使用效果

一次典型请求的体验如下：

1. 选择项目和权限范围，输入需求。
2. Agent 分析问题并选择 Skill、工具或 MCP；Multi Agent 会生成可追踪的 Todo。
3. 系统按 Todo 执行工具，展示工具请求、结果、模型分析、验证结论和下一步计划。
4. 涉及写入或命令执行时，按权限模式请求确认；失败时保留清晰的工具错误和恢复建议。
5. 执行结束后展示最终汇总、修改文件、验证证据和可继续处理的入口。

项目开发模式会把流程扩展为“需求分析 → 设计确认 → 长期开发 → 自动验证 → 用户验收”，适合前端、后端和全栈的中大型需求。

## 文档

- [用户手册](web/manual.html)：从页面操作 MiniCode。
- [Laya 决策模型设计](docs/LAYA_DECISION_MODEL_DESIGN.md)：决策模型职责边界、能力摘要、Agent/工具选择、Todo 验收、记忆多类型评分、压缩等级与异常降级方案。
- [Harness 技术说明](docs/HARNESS_README.md)：统一入口、执行约束、Trace 和能力边界的实现状态。
- [执行稳定性详解与 DeepCode 对比](docs/STABILITY_OPERATIONS_MANUAL.md)：逐项解释环境预检、执行入口、失败降级、策略 Hook 注册与重授权、并发缓存、外部动作核对、计划版本、嵌套作用域隔离与持久化写入防线、证据边界及后续验收清单。
- [详细执行调试日志](docs/DEBUG_TRACE.md)：独立于普通执行过程的可开关调试追踪、前端查看接口和脱敏边界。
- [金融数据源与工具契约](docs/FINANCIAL_DATA_SOURCE_PLUGINS.md)：数据集能力、HTTP/Python 插件、API Key 门禁和按数据集路由方式。
- [DeepCode 可靠执行对齐计划](docs/DEEPCODE_ALIGNMENT_OPTIMIZATION_PLAN.md)：按当前源码核对阶段进度，详解异常副作用保护、计划版本与历史快照、旧结果和 checkpoint 隔离、同实例运行中重入保护，以及尚未验收的恢复能力。
- [系统稳定性说明](docs/STABILITY_SYSTEM_GUIDE.md)：快速概览；完整实现状态与详细对比以执行稳定性详解为准。
- [记忆处理设计与 agentmemory 参考](docs/MEMORY_SYSTEM_DESIGN.md)：历史词项索引、待补建标记与重启续建、会话级状态查询和主动补建 API、相关性召回、完整内容去重、预算控制及锁竞争降级。
- [Harness 实现状态](docs/HARNESS_IMPLEMENTATION_STATUS.md)：当前已完成、部分实现和明确未实现的能力清单。
- [Multi Agent 子 Agent 架构](docs/MULTI_AGENT_SUBAGENT_ARCHITECTURE.md)：Single Agent、Multi Agent 和子 Agent 的职责边界。
- [Multi Agent 设计参考](docs/MULTI_AGENT_README.md)：主 Agent、SubAgent 和调度生命周期设计。
- [技术架构说明](docs/TECHNICAL_ARCHITECTURE.md)：统一入口、执行身份、工具契约、持久化和页面边界。
- [Agent 执行流程](docs/AGENT_EXECUTION_FLOW.md)：模型、工具、验证和恢复的详细调用链。
- [功能总览](docs/PROJECT_FEATURE_CATALOG.md)：已实现能力、边界和验证入口。
- [自动化端到端验证](docs/AUTOMATED_E2E_TESTING.md)：服务启动、真实请求和完成门禁验证方式。
- [v1.0.2 发布说明](docs/RELEASE_NOTES_v1.0.2.md)：本版本稳定性、权限审批、Agent 路由、MCP 自动选择和界面优化清单。
- [测试与临时目录治理](docs/TESTING_AND_TEMPORARY_FILES.md)：使用 `python scripts/run_tests.py -q`，统一管理测试缓存、失败样本保留和安全清理。

README 只介绍项目使用方式和整体效果；模块职责、事件字段、数据结构和架构约束请以 `docs/` 下的技术文档为准。

## 测试

运行核心回归测试：

```powershell
python -m pytest tests
```

如需验证完整服务流程，参见 `docs/AUTOMATED_E2E_TESTING.md` 和 `scripts/auto_e2e_test.py`。

## 主 Agent 规划与连续执行

对于“按照上面的规划开始实施吧”“继续上一轮任务”这类上下文依赖型请求，主 Agent 不会只根据当前一句话和 Skill 直接拆分 Todo。标准流程是：

1. 先识别请求是新任务、继续规划、修改规划、重试失败节点还是需要澄清。
2. 从连续会话、持久化 Todo、执行证据、用户提到的文件和工作区候选文件中恢复规划，并确认规划是否完整。
3. 基于当前问题和已恢复内容生成初步 Todo。
4. 由主 Agent 进行只读扫描，检查规划文件、代码现状、已完成 Todo、失败证据和依赖关系，再更新 Todo 图。
5. 只有最终 Todo 图确认后，才交给 AgentLoop 按依赖执行；子 Agent 只能执行分派到自己的 Todo，不能自行修改主计划。
6. 执行后由主 Agent 根据验收条件判断是否满足目标；不满足时只更新受影响节点并继续执行，满足后才生成最终汇总。

如果用户引用了上一轮规划但系统无法恢复规划内容，主 Agent 会进入可恢复的“需要补充规划上下文”状态，不会凭空编造实施计划。Todo、工具调用、失败原因、验证状态和重试/回滚结果都会保留到下一轮连续会话中。

详见 [Agent 执行流程](docs/AGENT_EXECUTION_FLOW.md) 和 [Multi Agent 设计参考](docs/MULTI_AGENT_README.md)。

## Todo 规划

多事项请求会生成有序的 Todo 依赖图：先满足依赖，再优先处理系统影响更大的就绪事项，最后在影响相当时优先处理更简单的事项。详见 [Todo 规划与调度](docs/TODO_PLANNING.md)。

## Roadmap

- 完善 Trace 的层级回放：补充模型调用、Todo、工具和验证节点的 Span 关联。
- 完善 Multi Agent 子 Agent 的生命周期、隔离、预算和失败节点局部恢复。
- 增强并发 DAG、失败节点局部重试和资源预算控制。
- 完善能力组合、Skill/MCP 导入审计、版本管理和回滚。
- 增强跨平台 Sandbox、浏览器外部动作核对和更完整的自动化验收能力。
- 持续减少重复实现，保持 Harness 主干清晰，细节通过可注册能力扩展。

## 目录概览

```text
minicode/
  api/                 HTTP、SSE 和静态页面入口
  core/harness.py      应用统一调度入口
  core/agent/          Single Agent、Multi Agent 和调度实现
  core/capabilities/   Tools、Skills、MCP 和 ToolResult
  core/service/        Session、Turn 和后台执行服务
  core/persistence/    SQLite、事件和执行投影
  core/sandbox/        命令执行与进程边界
web/                   浏览器端页面
docs/                  用户手册与技术设计
tests/                 自动化测试
```

## 贡献

提交代码前请运行相关测试，并同步更新受影响的 `docs/` 文档。架构改动优先保持 `Harness.start_turn()` 作为统一入口，避免在 Agent、工具和前端分别增加相互独立的执行协议。

## 版本发布

- [v1.0.3 发布说明](docs/RELEASE_NOTES_v1.0.3.md)：Todo 扫描、完整功能列表、多批次规划与执行、Esc 中断、执行恢复、验证权限和进度界面优化。