常见问题与故障排除

学完你能做什么

快速定位和解决初始化时的目录问题
排查 AI 助手启动失败的原因
理解阶段失败的处理流程（重试/回滚/人工介入）
解决依赖安装和版本冲突问题
处理 Agent 越权错误
使用 factory continue 分会话恢复执行

你现在的困境

你可能遇到了这些问题：

❌ 执行 factory init 时提示"目录非空"
❌ AI 助手无法启动，不知道如何配置权限
❌ 流水线执行到某个阶段突然失败，不知道如何继续
❌ 依赖安装报错，版本冲突严重
❌ Agent 生成产物被标记为"越权"
❌ 不理解检查点和重试机制

别担心，这些问题都有明确的解决方案。本教程会帮你快速排查和修复各类故障。

🎒 开始前的准备

前置知识

开始前，请确保你已经：

[ ] 完成了安装与配置
[ ] 完成了初始化 Factory 项目
[ ] 理解了 7 阶段流水线概览
[ ] 知道如何使用 Claude Code 集成

核心思路

AI App Factory 的故障处理遵循一套严格的策略，理解这套机制会让你在遇到问题时不再手足无措。

失败处理的三个层次

自动重试：每个阶段允许重试一次
回滚存档：失败产物移至 _failed/，回滚到上一个成功检查点
人工介入：连续失败两次后暂停，需要你手动修复

越权处理规则

Agent 写入未授权目录 → 移至 _untrusted/
流水线暂停，等待你审查
根据需要调整权限或修改 Agent 行为

权限边界

每个 Agent 都有严格的读写权限范围：

Agent	可读取	可写入
bootstrap	无	`input/`
prd	`input/`	`artifacts/prd/`
ui	`artifacts/prd/`	`artifacts/ui/`
tech	`artifacts/prd/`	`artifacts/tech/`, `artifacts/backend/prisma/`
code	`artifacts/ui/`, `artifacts/tech/`, `artifacts/backend/prisma/`	`artifacts/backend/`, `artifacts/client/`
validation	`artifacts/backend/`, `artifacts/client/`	`artifacts/validation/`
preview	`artifacts/backend/`, `artifacts/client/`	`artifacts/preview/`

初始化问题

问题 1：目录非空错误

症状：

bash

$ factory init
Error: Directory is not empty or contains conflicting files

原因：当前目录包含冲突文件（不是 .git、README.md 等允许的文件）。

解决方案：

bash

ls -la

清理冲突文件：

bash

# 方法 1：删除冲突文件
rm -rf <conflicting-files>

# 方法 2：移动到新目录
mkdir ../my-app && mv . ../my-app/
cd ../my-app

重新初始化：

bash

factory init

允许的文件：.git、.gitignore、README.md、.vscode/*、.idea/*

问题 2：已存在 Factory 项目

症状：

bash

$ factory init
Error: This is already a Factory project

原因：目录已包含 .factory/ 或 artifacts/ 目录。

解决方案：

如果是新项目，先清理再初始化：

bash

rm -rf .factory artifacts
factory init

如果想恢复旧项目，直接运行 factory run

问题 3：AI 助手启动失败

症状：

bash

$ factory init
✓ Factory project initialized
Could not find Claude Code installation.

原因：未安装 Claude Code 或未正确配置。

解决方案：

安装 Claude Code：

bash

# macOS
brew install claude

# Linux (从官网下载)
# https://claude.ai/code

验证安装：

bash

claude --version

手动启动：

bash

# 在 Factory 项目目录下
claude "请阅读.factory/pipeline.yaml和.factory/agents/orchestrator.checkpoint.md，启动流水线"

手动启动流程：1. 阅读 pipeline.yaml → 2. 阅读 orchestrator.checkpoint.md → 3. 等待 AI 执行

流水线执行问题

问题 4：非项目目录错误

症状：

bash

$ factory run
Error: Not a Factory project. Run 'factory init' first.

原因：当前目录不是 Factory 项目（缺少 .factory/ 目录）。

解决方案：

确认项目结构：

bash

ls -la .factory/

切换到正确目录或重新初始化：

bash

# 切换到项目目录
cd /path/to/project

# 或重新初始化
factory init

问题 5：Pipeline 文件未找到

症状：

bash

$ factory run
Error: Pipeline configuration not found

原因：pipeline.yaml 文件缺失或路径错误。

解决方案：

检查文件是否存在：

bash

ls -la .factory/pipeline.yaml
ls -la pipeline.yaml

手动复制（如果文件丢失）：

bash

cp /path/to/factory/source/hyz1992/agent-app-factory/pipeline.yaml .factory/

重新初始化（最可靠）：

bash

rm -rf .factory
factory init

阶段失败处理

问题 6：Bootstrap 阶段失败

症状：

input/idea.md 不存在
idea.md 缺少关键章节（目标用户、核心价值、假设）

原因：用户输入信息不足，或 Agent 未正确写入文件。

处理流程：

1. 检查 input/ 目录是否存在 → 不存在则创建
2. 重试一次，提示 Agent 使用正确的模板
3. 若仍失败，请求用户提供更详细的产品描述

手动修复：

bash

ls -la artifacts/_failed/bootstrap/

bash

mkdir -p input

提供详细的产品描述：

向 AI 提供更清晰、更详细的产品想法，包含：

目标用户是谁（具体画像）
核心痛点是什么
想要解决什么问题
初步的功能想法

问题 7：PRD 阶段失败

症状：

PRD 包含技术细节（违反职责边界）
Must Have 功能 > 7 个（范围蔓延）
缺少非目标（未明确边界）

原因：Agent 越界或范围控制不严。

处理流程：

1. 验证 prd.md 不包含技术关键词
2. 验证 Must Have 功能数量 ≤ 7
3. 验证目标用户有具体画像
4. 重试时提供具体的修正要求

常见错误示例：

错误类型	错误示例	正确示例
包含技术细节	"使用 React Native 实现"	"支持 iOS 和 Android 平台"
范围蔓延	"包含支付、社交、消息等 10 个功能"	"核心功能不超过 7 个"
目标模糊	"所有人都可以使用"	"25-35 岁的城市白领"

手动修复：

检查失败的 PRD：

bash

cat artifacts/_failed/prd/prd.md

修正内容：

删除技术栈描述
精简功能列表到 ≤ 7 个
补充非目标列表

手动移动到正确位置：

bash

mv artifacts/_failed/prd/prd.md artifacts/prd/prd.md

问题 8：UI 阶段失败

症状：

页面数量 > 8（范围蔓延）
预览 HTML 文件损坏
使用 AI 风格（Inter 字体 + 紫色渐变）
YAML 解析失败

原因：UI 范围过大或未遵循审美指南。

处理流程：

1. 统计 ui.schema.yaml 中的页面数量
2. 尝试在浏览器中打开 preview.web/index.html
3. 验证 YAML 语法
4. 检查是否使用禁止的 AI 风格元素

手动修复：

验证 YAML 语法：

bash

npx js-yaml .factory/artifacts/ui/ui.schema.yaml

在浏览器中打开预览：

bash

open artifacts/ui/preview.web/index.html  # macOS
xdg-open artifacts/ui/preview.web/index.html  # Linux

精简页面数量：检查 ui.schema.yaml，确保页面数量 ≤ 8

问题 9：Tech 阶段失败

症状：

Prisma schema 语法错误
引入微服务、缓存等过度设计
数据模型过多（表数量 > 10）
缺少 API 定义

原因：架构复杂化或数据库设计问题。

处理流程：

1. 运行 npx prisma validate 验证 schema
2. 检查 tech.md 是否包含必要章节
3. 统计数据模型数量
4. 检查是否引入非必要复杂技术

手动修复：

验证 Prisma Schema：

bash

cd artifacts/backend/
npx prisma validate

简化架构：检查 artifacts/tech/tech.md，移除非必要技术（微服务、缓存等）
补充 API 定义：确保 tech.md 包含所有必需的 API 端点

问题 10：Code 阶段失败

症状：

依赖安装失败
TypeScript 编译错误
缺少必要文件
测试失败
API 无法启动

原因：依赖版本冲突、类型问题或代码逻辑错误。

处理流程：

1. 运行 npm install --dry-run 检查依赖
2. 运行 npx tsc --noEmit 检查类型
3. 对照文件清单检查目录结构
4. 运行 npm test 验证测试
5. 若以上全部通过，尝试启动服务

常见依赖问题修复：

bash

# 版本冲突
rm -rf node_modules package-lock.json
npm install

# Prisma 版本不匹配
npm install @prisma/client@latest prisma@latest

# React Native 依赖问题
npx expo install --fix

TypeScript 错误处理：

bash

# 检查类型错误
npx tsc --noEmit

# 修复后重新验证
npx tsc --noEmit

目录结构检查：

确保包含以下必需文件/目录：

artifacts/backend/
├── package.json
├── tsconfig.json
├── prisma/
│   ├── schema.prisma
│   └── seed.ts
├── src/
│   ├── index.ts
│   ├── lib/
│   └── routes/
└── vitest.config.ts

artifacts/client/
├── package.json
├── tsconfig.json
├── app.json
└── src/

问题 11：Validation 阶段失败

症状：

验证报告不完整
严重问题过多（错误数 > 10）
安全问题（检测到硬编码密钥）

原因：Code 阶段质量差或存在安全问题。

处理流程：

1. 解析 report.md 确认所有章节存在
2. 统计严重问题数量
3. 若严重问题 > 10，建议回滚到 Code 阶段
4. 检查安全扫描结果

手动修复：

查看验证报告：

bash

cat artifacts/validation/report.md

修复严重问题：根据报告逐项修复
回滚到 Code 阶段（如果问题太多）：

bash

factory run code  # 从 Code 阶段重新开始

问题 12：Preview 阶段失败

症状：

README 不完整（缺少安装步骤）
Docker 构建失败
部署配置缺失

原因：内容遗漏或配置问题。

处理流程：

1. 检查 README.md 包含所有必要章节
2. 尝试 docker build 验证 Dockerfile
3. 检查部署配置文件是否存在

手动修复：

验证 Docker 配置：

bash

cd artifacts/preview/
docker build -t my-app .

检查部署文件：

确保存在以下文件：

artifacts/preview/
├── README.md
├── Dockerfile
├── docker-compose.yml
└── .github/workflows/ci.yml  # CI/CD 配置

越权错误处理

问题 13：Agent 越权写入

症状：

bash

Error: Unauthorized write to <path>
Artifacts moved to: artifacts/_untrusted/<stage-id>/
Pipeline paused. Manual intervention required.

原因：Agent 向未授权的目录或文件写入内容。

解决方案：

检查越权文件：

bash

ls -la artifacts/_untrusted/<stage-id>/

审查权限矩阵：确认该 Agent 的可写入范围
选择处理方式：
- 方案 A：修正 Agent 行为（推荐）
在 AI 助手中明确指出越权问题，要求修正。
- 方案 B：移动文件到正确位置（谨慎）
如果你确信文件应该存在，手动移动：
bash
```
mv artifacts/_untrusted/<stage-id>/<file> artifacts/<target-stage>/
```
- 方案 C：调整权限矩阵（高级）
修改 .factory/policies/capability.matrix.md，增加该 Agent 的写入权限。
继续执行：

bash

factory continue

示例场景：

Code Agent 试图修改 artifacts/prd/prd.md（违反职责边界）
UI Agent 试图创建 artifacts/backend/ 目录（超出权限范围）
Tech Agent 试图写入 artifacts/ui/ 目录（越界）

分会话执行问题

问题 14：Token 不足或上下文累积

症状：

AI 回答变慢
上下文过长导致模型性能下降
Token 消耗过大

原因：同一会话中累积了太多对话历史。

解决方案：使用 factory continue

factory continue 命令允许你：

保存当前状态到 .factory/state.json
启动新的 Claude Code 窗口
从当前阶段继续执行

执行步骤：

查看当前状态：

bash

factory status

输出示例：

bash

Pipeline Status:
───────────────────────────────────────
Project: my-app
Status: Waiting
Current Stage: tech
Completed: bootstrap, prd, ui

在新的会话中继续：

bash

factory continue

效果：

每个阶段独享干净上下文
避免 Token 累积
支持中断恢复

手动启动新会话（如果 factory continue 失败）：

bash

# 重新生成权限配置
claude "请重新生成.claude/settings.local.json，允许 Read/Write/Glob/Bash 操作"

# 手动启动新会话
claude "请继续执行流水线，当前阶段是 tech"

环境和权限问题

问题 15：Node.js 版本过低

症状：

bash

Error: Node.js version must be >= 16.0.0

原因：Node.js 版本不满足要求。

解决方案：

检查版本：

bash

node --version

升级 Node.js：

bash

# macOS
brew install node@18
brew link --overwrite node@18

# Linux (使用 nvm)
nvm install 18
nvm use 18

# Windows (从官网下载)
# https://nodejs.org/

问题 16：Claude Code 权限问题

症状：

AI 提示"没有读写权限"
AI 无法访问 .factory/ 目录

原因：.claude/settings.local.json 权限配置不正确。

解决方案：

检查权限文件：

bash

cat .claude/settings.local.json

重新生成权限：

bash

factory continue  # 自动重新生成

或手动运行：

bash

node -e "
const { generateClaudeSettings } = require('./cli/utils/claude-settings');
generateClaudeSettings(process.cwd());
"

正确权限配置示例：

json

{
  \"allowedCommands\": [\"npm\", \"npx\", \"node\", \"git\"],
  \"allowedPaths\": [
    \"/absolute/path/to/project/.factory\",
    \"/absolute/path/to/project/artifacts\",
    \"/absolute/path/to/project/input\",
    \"/absolute/path/to/project/node_modules\"
  ]
}

问题 17：网络问题导致依赖安装失败

症状：

bash

Error: Network request failed
npm ERR! code ECONNREFUSED

原因：网络连接问题或 npm 源访问失败。

解决方案：

检查网络连接：

bash

ping registry.npmjs.org

切换 npm 源：

bash

# 使用淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

重新安装依赖：

bash

rm -rf node_modules package-lock.json
npm install

人工介入决策树

Stage 失败
    │
    ▼
是否第一次失败?
    ├─ Yes → 自动重试
    │         │
    │         ▼
    │     重试成功? → Yes → 继续流程
    │            │
    │            No → 第二次失败
    │
    └─ No → 分析失败原因
              │
              ▼
          是输入问题吗?
              ├─ Yes → 修改输入文件
              │         └─ 回滚到上游 Stage
              │
              └─ No → 请求人工介入

决策要点：

第一次失败：允许自动重试，观察错误是否消失
第二次失败：停止自动处理，需要你手动审查
输入问题：修改 input/idea.md 或上游产物
技术问题：检查依赖、配置或代码逻辑
越权问题：审查权限矩阵或 Agent 行为

踩坑提醒

❌ 常见错误

直接修改上游产物
错误做法：在 PRD 阶段修改 input/idea.md
正确做法：回滚到 Bootstrap 阶段
忽略检查点确认
错误做法：快速跳过所有检查点
正确做法：仔细检查每个阶段的产物是否符合预期
手动删除失败的产物
错误做法：删除 _failed/ 目录
正确做法：保留失败的产物用于对比分析
修改后不重新生成权限
错误做法：修改项目结构后不更新 .claude/settings.local.json
正确做法：运行 factory continue 自动更新权限

✅ 最佳实践

早期失败：尽早发现问题，避免在后续阶段浪费时间
详细日志：保留完整的错误日志，便于排查问题
原子操作：每个阶段的输出应该是原子的，便于回滚
保留证据：失败产物归档后再重试，便于对比分析
渐进重试：重试时提供更具体的指导，而非简单重复

本课小结

本课程覆盖了 AI App Factory 使用过程中的各类常见问题：

类别	问题数	核心解决方法
初始化	3	清理目录、安装 AI 助手、手动启动
流水线执行	2	确认项目结构、检查配置文件
阶段失败	7	重试、回滚、修复后重新执行
越权处理	1	审查权限矩阵、移动文件或调整权限
分会话执行	1	使用 `factory continue` 启动新会话
环境权限	3	升级 Node.js、重新生成权限、切换 npm 源

关键要点：

每个阶段允许自动重试一次
连续失败两次后需要人工介入
失败产物自动归档到 _failed/
越权文件移至 _untrusted/
使用 factory continue 节省 Token

记住：

遇到问题不要慌，先看错误日志，再检查对应的产物目录，参考本课程的解决方案逐步排查。大多数问题都可以通过重试、回滚或修复输入文件来解决。

下一课预告

下一课我们学习 最佳实践。
你会学到：
如何提供清晰的产品描述
如何利用检查点机制
如何控制项目范围
如何逐步迭代优化

相关阅读：

失败处理与回滚 - 深入了解失败处理策略
权限与安全机制 - 理解能力边界矩阵
上下文优化 - 节省 Token 的技巧

附录：源码参考

点击展开查看源码位置

更新时间：2026-01-29

功能	文件路径	行号
初始化目录检查	`cli/commands/init.js`	32-53
AI 助手启动	`cli/commands/init.js`	119-147
失败策略定义	`policies/failure.policy.md`	1-276
错误码规范	`policies/error-codes.md`	1-469
能力边界矩阵	`policies/capability.matrix.md`	1-23
流水线配置	`pipeline.yaml`	全文
调度器核心	`agents/orchestrator.checkpoint.md`	1-301
Continue 命令	`cli/commands/continue.js`	1-144

关键常量：

允许的 Must Have 功能数量：≤ 7
允许的 UI 页面数量：≤ 8
允许的数据模型数量：≤ 10
重试次数：每个阶段允许重试一次

关键函数：

isFactoryProject(dir) - 检查是否为 Factory 项目
isDirectorySafeToInit(dir) - 检查目录是否可初始化
generateClaudeSettings(projectDir) - 生成 Claude Code 权限配置
factory continue - 在新会话中继续执行流水线

常见问题与故障排除 ​

学完你能做什么 ​

你现在的困境 ​

🎒 开始前的准备 ​

核心思路 ​

失败处理的三个层次 ​

越权处理规则 ​

权限边界 ​

初始化问题 ​

问题 1：目录非空错误 ​

问题 2：已存在 Factory 项目 ​

问题 3：AI 助手启动失败 ​

流水线执行问题 ​

问题 4：非项目目录错误 ​

问题 5：Pipeline 文件未找到 ​

阶段失败处理 ​

问题 6：Bootstrap 阶段失败 ​

问题 7：PRD 阶段失败 ​

问题 8：UI 阶段失败 ​

问题 9：Tech 阶段失败 ​

问题 10：Code 阶段失败 ​

问题 11：Validation 阶段失败 ​

问题 12：Preview 阶段失败 ​

越权错误处理 ​

问题 13：Agent 越权写入 ​

分会话执行问题 ​

问题 14：Token 不足或上下文累积 ​

环境和权限问题 ​

问题 15：Node.js 版本过低 ​

问题 16：Claude Code 权限问题 ​

问题 17：网络问题导致依赖安装失败 ​

人工介入决策树 ​

踩坑提醒 ​

❌ 常见错误 ​

✅ 最佳实践 ​

本课小结 ​

下一课预告 ​

附录：源码参考 ​

常见问题与故障排除

学完你能做什么

你现在的困境

🎒 开始前的准备

核心思路

失败处理的三个层次

越权处理规则

权限边界

初始化问题

问题 1：目录非空错误

问题 2：已存在 Factory 项目

问题 3：AI 助手启动失败

流水线执行问题

问题 4：非项目目录错误

问题 5：Pipeline 文件未找到

阶段失败处理

问题 6：Bootstrap 阶段失败

问题 7：PRD 阶段失败

问题 8：UI 阶段失败

问题 9：Tech 阶段失败

问题 10：Code 阶段失败

问题 11：Validation 阶段失败

问题 12：Preview 阶段失败

越权错误处理

问题 13：Agent 越权写入

分会话执行问题

问题 14：Token 不足或上下文累积

环境和权限问题

问题 15：Node.js 版本过低

问题 16：Claude Code 权限问题

问题 17：网络问题导致依赖安装失败

人工介入决策树

踩坑提醒

❌ 常见错误

✅ 最佳实践

本课小结

下一课预告

附录：源码参考