cloop

# Cloop Cloop 是“闭环”的戏称：一个本地助手，用于将未完成的心理环路卸载到您信任的系统中，然后帮助您检索、执行、关闭或释放它们，而无需在脑海中承载整个负担。 [](LICENSE) [](pyproject.toml)  ## 您所看到的 网页工作空间在一个专注的“执行”界面打开，而不是一个完整的待办事项列表： - **模式标签** 分隔捕获、执行、决策、规划、审查和回忆。 - **下一步面板** 将未完成的环路转化为一组即将到期、快速完成或高杠杆的行动。 - **动力学卡片** 解释当前视图的目的，以便系统降低认知负担，而不是增加另一个需要管理的控制台。 - **本地状态** 意味着相同的环路数据通过网页 UI、CLI、HTTP API 和 MCP 工具可用。 这就是核心承诺：捕获您的脑海中反复思考的内容，本地保存上下文，使下一步变得容易，从而真正关闭环路。 ## 为什么是“闭环” 环路是任何未解决的事情，您的思维反复重开：任务、忧虑、决策、跟进、提醒、想法、义务或您担心会丢失的上下文。Cloop 旨在将这些环路从精神 RAM 中卸载，保存在一个私有的本地系统中，并帮助将其转化为关闭或有意识的释放。 ## 适用人群 Cloop 适用于承载太多未解决环路的人，他们需要一个私有的本地助手/工具/代理来： - 将任务、提醒、忧虑、决策和半成品计划从工作记忆中卸载； - 将模糊的环路转化为清晰的下一步行动、审查提示或释放决策； - 在聊天记录之外保存持久的上下文和偏好； - 在本地文件中提问，并带有引用的检索上下文； - 为本地环路和记忆操作提供给 AI 代理一个狭窄、可审计的工具界面。 ## 问题 真正的负担不仅仅是任务，还包括反复承载未解决的认知状态： 1. 记住某事存在； 2. 记住为什么它很重要； 3. 记住执行所需的上下文； 4. 判断它是否仍然重要； 5. 找到可以关闭它的下一步。 大多数工具存储项目，但让大脑作为持久层。Cloop 将捕获、记忆、检索、审查和代理协助结合成一个本地优先的环路系统。助手可以帮助组织和检索，但确定性 Python 服务仍然负责验证、状态转换、幂等性、存储和可撤销的写入。 ## 功能 | 问题 | Cloop 功能 | 证明界面 | |---|---|---| | “我需要倾倒杂乱的想法，不需要先整理它们。” | 将原始文本、语音样式的倾倒、链接或证据转化为结构化的环路和记忆候选人的生活/捕获流程。 | 网页工作空间，`POST /life/message`，`uv run cloop capture ...` | | “我忘记了下一步行动是什么。” | 具有 inbox/actionable/blocked/scheduled/completed 状态的环路状态模型、下一个行动、到期日期、审查组和“下一步 5”优先级。 | 网页执行/审查标签，`uv run cloop next`，`/loops/next` | | “我的上下文被困在聊天中。” | 在网页、CLI、HTTP 和 MCP 中共享的持久记忆 CRUD/search。 | `uv run cloop memory ...`，记忆路由，`memory.*` MCP 工具 | | “我想要本地 RAG，但不需要建立基础设施。” | 递归摄入、切分、嵌入、SQLite 存储和基础询问/聊天响应。 | `uv run cloop ingest`，`uv run cloop ask`，`/ingest`，`/ask` | | “代理需要工具，但不能是无限制的权限。” | MCP 和 HTTP 突变界面重用共享的幂等性、验证、来源和审查/撤销合约。 | `cloop-mcp`，共享环路/审查/记忆服务 | 支持的摄入文件类型：`.txt`、`.md`、`.markdown`、`.pdf`。 ## 最快的体验方式 ### 1) 安装依赖 ```bash uv sync --all-groups pnpm --dir src/cloop/pi_bridge install --frozen-lockfile pnpm --dir frontend install --frozen-lockfile cp .env.example .env ``` 先决条件：Python 3.14+，Node 25.8.2+，pnpm 11.0.9+，`uv`，以及用于生成流的身份验证 `pi` 安装。 ### 2) 使用本地优先的启动配置 编辑 `.env`。对于第一次本地运行，保持自动化关闭，并使用 pi 进行生成和 Ollama 兼容的本地嵌入： ```dotenv CLOOP_PI_MODEL=zai/glm-5.2,kimi-coding/kimi-for-coding,openai-codex/gpt-5.5 CLOOP_PI_ORGANIZER_MODEL=zai/glm-5.2,kimi-coding/kimi-for-coding,openai-codex/gpt-5.5 CLOOP_PI_SELECTOR_MODE=fallback CLOOP_PI_CHAT_MAX_TOOL_ROUNDS=4 CLOOP_PI_PLANNING_MAX_TOOL_ROUNDS=2 CLOOP_PI_ENRICHMENT_MAX_TOOL_ROUNDS=2 CLOOP_PI_RAG_MAX_TOOL_ROUNDS=2 CLOOP_PI_MUTATION_MAX_TOOL_ROUNDS=2 CLOOP_EMBED_MODEL=ollama/nomic-embed-text CLOOP_OLLAMA_API_BASE=http://localhost:11434 CLOOP_AUTOPILOT_ENABLED=false CLOOP_SCHEDULER_ENABLED=false ``` `fallback` 向 `pi --list-models` 查询哪些选择器可用，并为每个角色选择 `pi --list-models` 报告为可用的第一个选择器。有关模型选择器、工具预算、重试、流式传输和嵌入的详细信息，请参见 [docs/ai_runtime.md](docs/ai_runtime.md)。 ### 3) 启动应用程序 ```bash make run ``` 在 `http://127.0.0.1:8000/` 打开网页工作空间，或在 `http://127.0.0.1:8000/docs` 打开 Swagger。 ### 4) 尝试 CLI 路径 ```bash uv run cloop capture "Return Amazon package by Friday" --tz-offset-min -420 uv run cloop loop list --status inbox uv run cloop next ``` 然后尝试文档检索： ```bash uv run cloop ingest ./my-docs uv run cloop ask "What does the onboarding process say about PTO?" --k 5 ``` `cloop ask` 返回带有 `answer`、`chunks`、`sources`、`metadata` 和 `rerun_action` 的 JSON。 ## 证明和验证 - **本地优先的数据平面**：环路和记忆数据存储在 SQLite（`core.db`）中；检索数据默认存储在 SQLite（`rag.db`）中。 - **传输一致性**：网页、CLI、HTTP 和 MCP 重用共享的环路、记忆、RAG、审查、规划和幂等性服务，而不是分叉实现。 - **本地验证**：从 `make help` 开始，在迭代过程中使用 `make check-fast`，并运行 `make ci` 进行完整的本地发布检查。 - **重点证明**：`make ci` 包括质量检查、桥接测试、前端构建/测试、Python 测试、软件包构建和元数据验证；使用 `make test-all` 或 `make test-performance` 需要性能指标覆盖。 有关引导式烟雾测试路径，请使用 [docs/verification_checklist.md](docs/verification_checklist.md)。 ## 工作原理 ```mermaid flowchart LR UI[网页 UI] --> API[FastAPI 应用] CLI[CLI] --> API MCP[MCP 服务器] --> SERVICES[共享服务] API --> SERVICES SERVICES --> LOOPS[环路 + 记忆服务] SERVICES --> RAG[RAG 服务] SERVICES --> REVIEW[审查 + 规划工作流] LOOPS --> CORE[(core.db)] RAG --> RAGDB[(rag.db)] SERVICES --> EVENTS[SSE + Webhooks] SCHED[cloop-scheduler] --> SERVICES ``` 关键设计选择： - Python 拥有确定性状态、存储、验证、幂等性、安全检查和工具执行。 - 生成式聊天和组织者调用通过 pi 桥接器进行。 - 嵌入使用单独的 LiteLLM 兼容提供商路径。 - HTTP、CLI、MCP 和网页界面调用相同的能力协调合约。 深入了解： - [docs/architecture.md](docs/architecture.md) — 系统形状、数据流、权衡。 - [docs/ai_runtime.md](docs/ai_runtime.md) — pi 桥接器、选择器回退/精确模式、流式传输有效载荷、嵌入。 - [docs/ux/experience-vision.md](docs/ux/experience-vision.md) — 意图的操作员体验。 - [docs/cloop-life-spec.md](docs/cloop-life-spec.md) — 自然语言 Life 流的产品规格。 - [docs/roadmap.md](docs/roadmap.md) — 当前产品路线图。 ## 当前状态和限制 - Cloop 设计用于本地/私有使用。直接暴露给公共互联网时，请添加自己的身份验证和边界控制。 - 生成式功能需要 `pi` 已安装、身份验证，并能够解析配置的选择器。 - 嵌入凭证/配置与 pi 聊天凭证分开。 - 调度器和自动驾驶仪默认关闭：`CLOOP_AUTOPILOT_ENABLED=false`，`CLOOP_SCHEDULER_ENABLED=false`。 - 支持可选的 SQLite 向量扩展，但不需要外部向量数据库。 - 完整的本地检查门（`make ci`）不包括标记为 `performance` 的测试；使用 `make test-all` 或 `make test-performance` 需要这些信号。 在 [SECURITY.md](SECURITY.md) 中查看安全报告和处理指南。 ## 完整设置说明 如果您需要清除默认的存储库本地 SQLite 状态并从头开始： ```bash make reset-local-data ``` 当启用调度时，请将其作为单独的进程运行： ```bash cloop-scheduler ``` ## 快速参考 - 网页应用：`make run`，然后打开 `http://127.0.0.1:8000/` - API 文档：`http://127.0.0.1:8000/docs` - CLI 帮助：`uv run cloop --help` - MCP 服务器：`uv run cloop-mcp` - 开发人员命令指南：`make help` ## 详细参考 在需要确切的命令、端点或配置详细信息时使用这些参考： - [CLI 参考](docs/reference.md#cli-reference) - [服务器和 API 端点](docs/reference.md#running-the-server) - [网页 UI 工作流](docs/reference.md#web-ui-workflow) - [配置](docs/reference.md#configuration) - [Webhooks 和 SSE](docs/reference.md#webhooks-and-sse) - [MCP 服务器](docs/reference.md#mcp-server) ## 本地验证策略 验证是本地优先的，并使用维护的 `make` 目标。 - `make help` 显示短命令指南。 - `make check-fast` 是正常的开发关卡。 - `make ci` 是完整的本地发布关卡：质量检查、桥接测试、前端构建/测试、Python 测试（不包括 `performance`）、软件包构建和元数据验证。 - `make test-all`、`make test-cov` 和 `make test-performance` 可在需要详尽、覆盖率或性能特定信号时使用。 有关引导式验证路径，请使用 [docs/verification_checklist.md](docs/verification_checklist.md)。 ## 开发 从短命令指南开始： ```bash make help ``` 大多数日常工作使用： - `make run` 启动本地 FastAPI 应用 - `make check-fast` 用于快速迭代 - `make ci` 用于完整的本地发布级验证 使用 `make help-all` 获取完整的目标列表，包括发布、覆盖率、性能和维护命令。 ## 项目维护文档 - [CONTRIBUTING.md](CONTRIBUTING.md) - [CHANGELOG.md](CHANGELOG.md) - [SECURITY.md](SECURITY.md) - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - [架构概述](docs/architecture.md) - [参考指南](docs/reference.md) - [验证检查清单](docs/verification_checklist.md) - [发布流程](docs/release.md) - [许可证](LICENSE) ## 发布和来源链接 - [发布](https://github.com/fitchmultz/cloop/releases) - [标签](https://github.com/fitchmultz/cloop/tags) ## 下一步 运行 `make help`，然后使用 `make run` 打开本地工作空间或 `make check-fast` 在更改存储库之前验证它。