# SimpleLoop

**Repository Path**: wfcz2026/simple-loop

## Basic Information

- **Project Name**: SimpleLoop
- **Description**: 。。。。。。。。。。。。。。。。。。。。。。。。。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-20
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SimpleLoop · AI 开发的精确任务编排器（规划层）

按照《SimpleLoop-软件设计文档-合并版.md》（v2.0）实现的 Phase 1 MVP：**需求 → 项目档案 → 软件设计 → 任务分解 → 任务包导出** 的全链路规划系统（不含执行层）。

## 已实现能力

**后端（FastAPI + SQLite）**
- 项目 / 需求 CRUD；项目档案构建：tree-sitter 静态分析（Python / JS / TS / TSX / Java / C / C++）+ 符号/引用/命令入口/规范/风险抽取 + FTS5 全文检索 + LLM 语义整理 + archive.md 双视图
- 设计智能体：七阶段管道（需求理解 → 歧义与假设 → 档案检索 → 结构规划 → 分节并行流式生成 → 自校验 + 修复轮 → 人工评审）、假设清单/待确认问题、design.md 双视图
- 任务分解智能体：功能点提取 → DAG 草构 → 任务细化 → 冲突消解（文件互斥/环检测）→ 自校验；任务卡完整 Schema（scope/verification/追溯/风险/阈值）、依赖边双向同步、decomposition.md 双视图
- LLM 网关：OpenAI 兼容协议（DeepSeek 等）、模型分级路由、重试、流式、JSON 模式、token 计量（Run 记录）；内置知识包（architecture / decompose / verification + 语言包）
- 校验服务：Schema + 语义 + DAG + 文件冲突；任务包导出 `task-package-v1`（zip / json / markdown）；追溯链三列视图
- Job 执行器 + SSE 事件流（设计文档 9.3 事件协议）；断点状态持久化；生成记录 Run 全程可查
- Phase 2 能力：AI 修复图问题（diff 预览 + 确认应用）、任务合并/拆分、历史参考档案关键词检索、版本快照与回退、单节重生成（SSE）、Job 硬超时保护
- 增量扫描（4.5）：文件级哈希复用，无变更时 5s 全量 → 0.5s 增量，LLM 语义层仅在结构变化时重生成；符号/引用 id 确定性生成保证追溯链跨扫描稳定
- 交互式澄清模式（5.3）：歧义点 Job 进入 `awaiting_input`，前端弹窗逐题回答后恢复生成
- A/B 对比（7.7）：`GET /runs/compare` 逐项对比两次生成记录（模型/token/耗时/修复轮次/校验/提示词版本），前端生成记录页勾选两条即可对比
- Phase 3 预留：执行状态回写协议 `POST /execution/status`（draft/ready/blocked/done，外部 Coding Agent 消费任务包后回写）

**前端（React 18 + TypeScript + Vite + Ant Design）**
- 项目列表页；项目详情：流程状态条 + 档案页 / 工作台（需求、设计、任务画布、导出）/ 生成记录页
- 任务画布：React Flow + dagre 自动布局，风险色标、依赖边类型（data/order/exclusive）、连线创建依赖、节点详情编辑、框选合并、拆分、AI 修复、问题面板
- Markdown 双视图预览（含 mermaid 图）；导出下载（zip/json/markdown）
- 知识包管理页（启用/禁用、编辑内容）；生成记录成本统计；需求 md/txt 文件上传；设计版本管理（快照 diff/回退）；画布模块分组过滤、泳道色标与泳道布局切换
- 画布结构操作：新建/复制/合并/拆分任务卡、子树重分解、任务图快照（创建/列表/回退）、AI 修复（diff 预览 + 确认应用）
- 参考档案库（另存为参考/列表/删除）；需求附件上传（后端落盘 data/attachments）

## 快速开始

```powershell
# 1) 后端（端口 8003，日志由 Python 写入 backend/data/server-8003.log）
cd backend
python -m pip install -r requirements.txt
python run_server.py --port 8003

# 2) 前端（端口 5173，/api 代理到 8003）
cd frontend
npm install
node node_modules\vite\bin\vite.js --host 127.0.0.1 --port 5173

# 浏览器访问 http://127.0.0.1:5173
```

或使用一键脚本（幂等重启后端 + 前端）：

```powershell
powershell -ExecutionPolicy Bypass -File tools\start_all.ps1
```

## 配置（backend/.env 或环境变量，前缀 `SIMPLELOOP_`）

| 变量 | 默认 | 说明 |
| --- | --- | --- |
| `SIMPLELOOP_LLM_API_KEY` | （空） | DeepSeek/OpenAI 兼容 API key；不配置则走确定性兜底路径（可离线演示） |
| `SIMPLELOOP_LLM_BASE_URL` | `https://api.deepseek.com/v1` | OpenAI 兼容端点 |
| `SIMPLELOOP_LLM_STRONG_MODEL` / `_LIGHT_MODEL` | `deepseek-chat` | 复杂/轻量任务分级路由 |
| `SIMPLELOOP_DATA_DIR` | `backend/data` | SQLite + 档案快照 + 导出物 + Run 记录 |

> API key 仅存于服务端配置文件/环境变量，前端不可见、接口不透传（设计文档 7.1 / 11.3）。

## 端到端冒烟测试

```powershell
# 需要后端运行在 8003（或设置 SIMPLELOOP_TEST_BASE 指向其它端口）
python tools\smoke_test.py
```

已验证流程：创建项目（扫描 `example-src/ontoFlow`，122 文件 / 682 符号 / 4 命令入口）→ 档案就绪 → 需求 → AI 设计（10 章节，校验通过）→ 任务分解（5 任务 / 5 依赖，校验通过）→ 导出 task-package-v1 zip。

## example-src 完整验证（44/44 通过）

`python tools/verify_example.py` 在 `example-src/ontoFlow` 上覆盖：全量/增量扫描（4.6s → 0.5s、符号不丢失）、符号检索、设计生成与自校验、章节编辑持久化、快照 diff/回退、任务分解（修复轮 + 确定性环/依赖消解）、合并/拆分、依赖双向同步、AI 修复、导出（zip/json）、追溯链、生成记录、按项目知识包启用、阈值配置、执行状态回写、单节重生成。

验证过程中发现并修复：增量重扫导致符号清空、合并时依赖边主键冲突、快照对比顺序、单节重生成缺少知识包上下文、分解输出环/卡边不一致时的确定性消解。

## 目录结构

```text
backend/
  app/
    api/            # REST + SSE 路由
    core/profiler/  # 静态分析：语言插件（tree-sitter）、扫描、档案组装、LLM 整理、archive.md
    core/designer/  # 设计智能体七阶段管道、design.md
    core/decomposer/# 拆解智能体、冲突消解、decomposition.md
    core/self_check/# Schema/语义/DAG/文件冲突校验
    core/exporter/  # task-package-v1 导出
    models/ schemas/ services/  # SQLAlchemy 实体、Pydantic 契约、LLM 网关/知识包/检索/Job
  data/             # SQLite + 快照 + 导出物 + Run（运行期生成，不入库）
  run_server.py     # 启动器（日志写文件，避免 PowerShell 重定向挂死）
frontend/
  src/pages/        # 项目列表、档案、工作台（需求/设计/任务画布/导出）、生成记录
  src/components/   # FlowCanvas、MarkdownView、CheckReportPanel
  src/api/ src/hooks/ src/stores/
tools/
  smoke_test.py     # 端到端冒烟测试
  restart_backend.ps1 / start_all.ps1
```

## 与设计文档的对应与取舍

- 任务图以 `task_cards` + `dependencies` 两表表达（TaskGraph 为派生视图，未建独立表）。
- 需求条目/章节 id 全部字符串化，LLM 输出的数字 id 会在归一化层纠偏。
- 无 API key 时设计与分解走确定性兜底（不阻塞演示）；配置 key 后自动切换到 LLM 精写版本。
- 画布编辑覆盖：任务增删改、依赖连线/删除、字段编辑、合并/拆分、AI 修复、模块过滤与泳道布局。
- 剩余 Phase 2/3：Java/C/C++ 增量语义优化、执行引擎对接（回写协议已预留、联调待外部 Agent）、多用户/权限迁移。
- 本机单用户部署（无登录/权限），数据仅存本机；档案扫描对目标仓库只读。
- 按用户确认：Phase 3 执行引擎联调与多用户/权限不在本期范围（执行状态回写协议已预留接口）。