Specloom 文档

从一句想法开始，在 VS Code / Cursor 中形成明确需求与可执行任务，并沿完整路径交付。本页覆盖安装、首次设置、日常使用与进阶能力。

快速开始

完成首次设置：打开 Specloom，按向导完成环境检测、选择 AI、连接测试和项目确认。
开始一件事：只有想法就选「记录一个想法」；需求已经明确则直接创建工作项。
查看并运行任务：在详情页确认任务路径后运行。点开任一节点可查看说明、内容、执行结果和历史尝试。

安装与 AI 配置

Specloom 目前通过公开 VSIX 安装。下载官网最新安装包后，在 VS Code / Cursor 扩展页右上角选择「从 VSIX 安装…」，安装完成后重载窗口：

1. 下载 specloom-<version>.vsix
2. 扩展页 → … → 从 VSIX 安装…
3. Developer: Reload Window

首次向导会展示本机可用的 AI，并要求真实连接测试。当前支持：

CLI Agent：Cursor Agent、Claude Code、OpenAI Codex；支持在明确授权后直接修改工作区。
模型/API：OpenAI 兼容 API 与 VS Code Language Model；适合文本生成或由宿主提供的模型能力。

插件通过官网 stable 清单检查更新。发现新版后可确认一键下载、校验并安装，不会静默更新，也不依赖 Marketplace 判定版本。

看板与详情面板

左侧活动栏包含需求孵化与交付看板两个入口。工作项沿七个生命周期阶段推进：

需求 → 产品 → 研发 → 测试 → 发布 → 运维 → 完成

每个工作项显示当前阶段和状态；重新打开项目或工作项时，原来的任务、产物和执行记录会继续显示。

工作项 → 阶段 → 任务节点 → 尝试记录 → 产物 / 证据

点击工作项进入详情，可以查看完整执行路径。每个任务节点都包含任务说明、依赖、输入、输出、状态、耗时和历史尝试。

SDD 流水线

流水线不是一串黑盒提示词。每个阶段会展开为格式化任务，并记录真实输入、输出、命令、测试和发布证据：

[需求澄清] → [规格 / 原型] → [方案 / 开发] → [单测 / 验收] → [发布 / 归档]

推荐顺序：先确认需求和验收标准，再执行下游任务。上游变化时，受影响的证据与产物会标记过期。

步骤	输入	产出	自动阶段流转
需求 / 规格	想法、约束、项目上下文	结构化需求、假设、验收标准	需求 → 产品
产品 / 方案	已确认规格	原型、验收方案、技术设计	产品 → 研发
开发	冻结任务与方案	工作区代码、变更摘要、追溯映射	研发
测试 / 发布	真实代码与构建结果	单测、验收、发布事实与交付档案	测试 → 发布 → 完成

写入工作区与外部副作用

支持写文件的 CLI Agent 可以在确认后直接修改当前工作区。执行前会冻结模型、目录、写入范围、命令和门禁；测试、Docker 或 GitHub 发布结果会记录为可复查事实。

档位与门禁

同一份规格同时支撑两种节奏，你只需选择编织进多少人审：

简单档：低风险、边界清晰的需求一键贯穿全程，无需人工交接。
标准档：在规格、技术方案、发布等关键节点逐道人审，由人确认通过或驳回。

门禁分三类，可按团队 / 应用为每道工序自由编排：

人工评审：停下等人审批通过或驳回。
命令校验：跑一条命令 / CI，通过才放行。
自动放行：无需停留，直接续跑下一阶段。

进阶能力（可选，默认关）

以下能力把「让 AI 按规范产出 + 自动化 + 度量」做扎实，全部 opt-in，默认关闭即行为不变：

能力	设置 / 入口	一句话
项目级全局约束 Steering	`.lifecycle/steering/*.md`	写一次团队规范/技术栈/安全基线，所有阶段的 AI 都遵守。
事件驱动自动化 Hooks	`.lifecycle/hooks.json`	「代码落盘→跑测试」「spec 改→重生过期产物」等事件自动触发。
原子步骤执行	`atomicSteps`	大变更拆成小步逐个实现 + 校验 + 提交，失败停在该步不整笔废。
双轮校验防幻觉	`verifyCodeGrounding`	独立 Agent 核对代码引用的符号/依赖是否真实存在。
Spec 自反馈	`specFeedback`	交付后回看规格质量，沉淀改进 backlog 并打分。
AI 效果度量	管理看板「AI 效果」	采纳/重生率、首次正确率 FPY、规格质量分。

数据与产物

项目配置、工作项、任务运行、产物和交付记录保存在 .lifecycle/，可随 git 管理并在重开项目后恢复：

<你的项目>/
└── .lifecycle/
    ├── project.json          # 项目与应用配置
    ├── items.json            # 工作项与生命周期状态
    ├── runs/                 # 任务快照、执行报告与证据
    └── <工作项id>/            # 规格、方案、测试与交付产物

已有源码默认留在当前文件夹，不会被搬家。外部 AI 会接收完成任务所需的受控上下文；关键存储损坏或迁移不可信时，Specloom 会进入受限只读模式而不是继续覆盖数据。

常见问题

AI 工具探测或连接测试失败

打开「Specloom: Agent AI 工具设置」，检查 Cursor / Claude / Codex 的可执行路径、登录状态和明确模型，然后重新运行连接测试。

报错「未找到可用的语言模型」（vscode-lm 模式）

需安装并登录可提供模型的扩展（如 GitHub Copilot）。

点「打开」提示文档不存在

.lifecycle/<id>/ 下的产物被手工删除了，重新「生成」即可。

任务为什么停住或没有推进

打开对应任务查看阻断原因。常见原因包括前置任务未完成、证据已过期、命令或测试失败、需要人工门禁，或外部执行结果需要对账。

产物没落盘，只开了临时文档

当前没打开工作区文件夹，请在扩展宿主窗口打开一个文件夹后重试。