solo-build-free

构建执行引擎(免费版)

执行实现计划中的任务,采用TDD工作流、自动提交与阶段门检查。从 plan.md 选取下一个未完成任务,实现、提交、更新进度,直至全部完成.

请求格式

能力一览

1. 轨道选择

• 通过参数指定轨道ID:验证 {plan_root}/{argument}/plan.md 存在
• 通过 --task X.Y 跳转到指定任务
• 无参数时:搜索 docs/plan/ 下所有 plan.md,列出有未完成任务的轨道,多个时询问用户

2. 上下文加载

并行读取必要文档,不读源码:

• docs/plan/{trackId}/plan.md — 任务列表(必需)
• docs/plan/{trackId}/spec.md — 验收标准(必需)
• docs/workflow.md — TDD策略、提交策略(若存在)
• 项目配置文档 — 架构、Do/Don't
• .solo/pipelines/progress.md — 前次迭代记录(若存在)

3. 任务恢复

检测 plan.md 中 [~] 标记的中断任务:

• 显示:上次任务、当前进度
• 选项:从断点继续 / 重启当前任务 / 先看进度摘要
• 通过询问用户后继续

4. 任务执行循环

扫描 plan.md 中所有 - [ ] 或 - [~] 任务,若全部 [x] 则跳到完成流程。否则逐个执行:

1. 查找下一个任务:解析 - [ ] Task X.Y: 行
2. 启动任务:[ ] → [~],宣布 "Starting Task X.Y"
3. 研究:用 project_code_search 找相关代码,只读top 2-3结果
4. TDD或直接实现
5. 集成测试
6. 完成任务:[~] → [x],提交
7. 阶段完成检查

输出格式

完成响应以Markdown格式返回,包含任务状态(成功/失败)、解析摘要和具体输出数据。失败时返回错误码和错误信息,便于定位问题。- 验证返回数据的完整性和格式正确性

适用范围

不适用于:计划创建(用 /plan)、部署(用 /deploy)、代码审查(用 /review)、无plan.md的项目.

使用指南

1. 确认 docs/plan/{trackId}/plan.md 与 spec.md 存在
2. 用工具或并行读取加载上下文(不读源码)
3. 扫描未完成任务,若全部完成跳到完成流程
4. 逐个执行任务:研究 → TDD/直接实现 → 集成测试 → 提交
5. 每阶段结束运行检查点
6. 全部完成后:最终验证 + 更新状态 + 输出 ``

示例展示

示例:任务执行循环

Starting Task 2.1: 实现用户登录接口
# ...
1. 研究: project_code_search(query="login auth", project="myapp")
   找到 src/auth/login.ts,读取
2. TDD Red: 写 tests/login.test.ts,运行 `make test` 确认失败
3. TDD Green: 实现 src/auth/login.ts,运行 `make test` 确认通过
4. TDD Refactor: 提取重复代码,运行 `make test` 确认仍通过
5. 集成测试: `make integration` 通过
6. 完成: plan.md [~] → [x],git commit -m "feat(auth): implement login API"

故障处理体系

注意事项

• 需要LLM支持,无LLM环境无法执行
• 依赖 plan.md 与 spec.md 存在,无计划无法执行
• 工具不可用时降级为文件搜索,效率降低

运行环境

运行环境

• Agent平台: 支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统: Windows / macOS / Linux

依赖项

API Key 配置

需要配置对应API Key，详见上文环境配置章节

可用性分类

• 分类: MD+EXEC（）

API Key配置方式:

export API_KEY=${API_KEY:?请设置环境变量}

配置后需重启会话或开启新终端生效。API Key应妥善保管,避免泄露到版本控制系统.

升级提示

本免费版提供基础功能。升级到完整版 solo-build 获取全部能力和高级特性.

边界条件与限制 (Boundary Conditions)

输入限制

• 输入数据格式不正确时，技能将无法执行，并返回错误信息。
• 输入中包含的路径或文件名无效时，技能将无法访问文件，并返回错误。
• 输入中包含的命令或参数不支持时，技能将返回错误并指出问题。

性能边界

• 在处理大量任务或大型项目时，技能的执行时间可能会增加。
• 并行处理大量任务时，资源消耗（如CPU和内存）可能会增加。

兼容性约束

• 技能主要针对支持SKILL.md的AI Agent平台设计，不同平台的兼容性可能存在差异。
• 技能依赖于LLM API，因此LLM服务的可用性和稳定性会影响技能的性能。
• 技能的执行依赖于本地文件系统和网络环境，网络不稳定或文件系统损坏可能导致技能无法正常运行。

上下文加载限制

• 上下文加载过程中，只读取指定路径下的文档，不读取源码，这可能导致某些依赖关系无法直接从源码中推断。
• 上下文加载过程中，可能无法访问某些外部资源或服务，这可能会影响任务执行的准确性。

任务执行限制

• 任务执行过程中，若遇到无法解决的问题或错误，技能将暂停执行并等待用户输入，这可能导致执行时间延长。
• 对于某些需要人工干预的任务，技能可能无法完全自动化执行。

输出格式限制

• 输出格式为Markdown，对于非Markdown格式的需求，技能可能无法满足。
• 输出内容可能包含敏感信息，如API密钥等，用户在使用时需注意保护这些信息。

其他限制

• 技能不支持计划创建、部署、代码审查等功能。
• 技能不支持无plan.md的项目。
• 技能的执行依赖于工具，若工具不可用，技能将降级为文件搜索，效率可能降低。

差异化优势

与同类方案对比

1. 手动操作：与手动执行计划任务相比，solo build free自动化了从任务选择到提交的整个流程，节省了大量的手动操作时间。手动操作通常需要开发者逐一查找任务、编写代码、进行测试和提交，而solo build free能够一次性完成这些步骤，大大提高了效率。

2. 通用自动化工具：与其他通用自动化工具相比，solo build free专注于构建执行引擎的特定需求，提供了更为精细化的任务管理和进度跟踪功能。通用工具可能需要额外的配置和定制才能达到与solo build free相同的效果，而solo build free直接针对开发工作流进行优化。

3. 其他构建工具：与传统的构建工具（如Makefile、CMake等）相比，solo build free提供了更直观的用户界面和更丰富的功能，如TDD工作流支持、阶段门检查等。传统构建工具通常需要更多的脚本编写和调试，而solo build free简化了这一过程。

独特功能

1. TDD工作流集成：solo build free内置了TDD工作流，允许开发者直接在构建过程中编写测试，确保代码质量。

2. 阶段门检查：在代码提交前，solo build free会自动执行阶段门检查，确保所有任务都已正确完成，避免因遗漏任务导致的错误。

3. 进度跟踪：solo build free能够实时跟踪任务进度，提供清晰的视图，帮助开发者了解项目状态。

4. 并行任务处理：solo build free支持并行处理多个任务，加快了构建过程。

5. 上下文加载：solo build free能够并行读取必要的文档，而不必读取源码，提高了效率。

效率提升

使用solo build free，开发者可以节省约50%的时间在任务执行和进度跟踪上。自动化流程减少了重复性工作，使开发者能够专注于更有价值的工作。

应用场景创新

1. 敏捷开发：solo build free能够帮助敏捷团队快速响应变化，提高开发效率。

2. 个人项目：对于独立开发者，solo build free简化了项目管理和构建过程，使其更容易维护和扩展。

3. 团队协作：solo build free可以与版本控制系统集成，方便团队成员之间的协作和代码共享。

创新优势

效率提升量化分析

差异化对比

核心痛点解决

问题处理指引

安全保障说明

1. 确保输入数据的安全性，防止注入攻击。
2. 限制技能的访问权限，防止未授权访问。
3. 定期更新技能，修复已知安全漏洞。
4. 对敏感操作进行审计，确保操作符合安全规范。
5. 使用安全的通信协议，保护数据传输安全。

安全风险防范

重要特性

• 自动化执行: 执行实现计划任务,TDD工作流,自动提交,阶段门检查,进度跟踪。(免费版)。执行实现计划任务的引擎:轨道选择、上下文加载
• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果
• 信息检索: 快速搜索和过滤目标数据

疑问解答集锦

Q1: 构建执行引擎(免费版)支持哪些输入格式？

A1: 执行实现计划任务,TDD工作流,自动提交,阶段门检查,进度跟踪。(免费版)。执行实现计划任务的引擎:轨道选择、上下文加载、任务恢复、 TDD工作流、集成测试、阶。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

构建执行引擎(免费版)通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块