doa-workcopilot

name	doa-workcopilot
description	项目全生命周期工作站。统一编排所有 Agent 和 Skill，从项目初始化到交付的一站式工作流。 自动识别新项目/老项目，引导需求分析、系统设计、任务拆解、脚手架搭建和工程轨道配置。 USE FOR: 开始新项目、接手老项目、初始化工作流、workcopilot、工作站、项目启动、 新建项目、项目脚手架、scaffold project、init project、start project、work copilot。 DO NOT USE FOR: 单个文档生成（直接用 doa-ppt / doa-metting 等）、纯代码调试（用 systematic-debugging）。
argument-hint	可选: "new" (新项目) | "existing" (老项目) | 留空则交互引导

DOA WorkCopilot — 项目全生命周期工作站

核心理念

一个项目的成功从第一行配置开始，而非第一行代码。 WorkCopilot 统一编排所有 Agent 和 Skill，确保每一步都有正确的角色、正确的约束、正确的产出。

🔒 自动持久化契约：每次会话结束时，WorkCopilot 自动更新 .workcopilot/ 下的项目状态文件（state.json、changelog.md、decisions.md、tech-debt.md），确保项目记忆永不丢失。无需用户手动触发。

---

🚀 团队部署（首次使用必读）

本 Skill 是完全自包含的，包含全部 Agent 定义、工作流和脚手架模板。 团队成员只需获取 doa-workcopilot/ 目录即可上手。

方式一：自动部署（推荐）

# 在 PowerShell 中执行
& "path/to/doa-workcopilot/scripts/deploy.ps1"

脚本会自动：

1. 将 skill 安装到 ~/.claude/skills/doa-workcopilot/
2. 在 ~/.claude/agents/ 安装 6 个 Agent 文件（已存在则跳过）
3. 在 ~/.claude/skills/ 安装 12 个附属 Skill（已存在则跳过）

方式二：手动部署

1. 复制 doa-workcopilot/ 到 ~/.claude/skills/
2. 复制 embedded-agents/ 下的6个 .md 文件到 ~/.claude/agents/
3. 复制 embedded-skills/ 下的12个子目录到 ~/.claude/skills/（已存在同名则跳过）

内置资源清单

doa-workcopilot/
├── SKILL.md                              ← 主编排逻辑（本文件）
├── scripts/
│   └── deploy.ps1                        ← 团队一键部署脚本
├── references/                           ← 脚手架模板 & 内嵌工作流
│   ├── agents.md                         ← 6 个 Agent 精简角色定义
│   ├── embedded-harness.md               ← Harness 工程轨道工作流
│   ├── embedded-spec-flow.md             ← Spec-Flow 结构化开发流程
│   ├── dotnet-scaffold.md                ← .NET 8 脚手架模板
│   ├── python-scaffold.md                ← FastAPI 脚手架模板
│   └── react-scaffold.md                 ← React + Vite 脚手架模板
├── embedded-agents/                      ← 完整 Agent 定义文件（项目注入用）
│   ├── requirements-analyst.md
│   ├── system-architect.md
│   ├── backend-engineer.md
│   ├── frontend-engineer.md
│   ├── test-engineer.md
│   └── mermaid-diagram.md
├── embedded-hooks/                       ← PreToolUse Hook（项目注入用）
│   ├── update-workcopilot.json           ← Hook 配置（commit/build/docker 前拦截）
│   └── scripts/
│       └── check-workcopilot.ps1         ← 拦截脚本（检查 .workcopilot 是否已更新）
├── embedded-prompts/                     ← Prompt 模板（项目注入用）
│   ├── code-review.prompt.md             ← 全面 Code Review（安全+性能+规范+逻辑）
│   └── generate-tests.prompt.md          ← 生成 xUnit + Moq 单元测试
└── embedded-skills/                      ← 完整 Skill 包（项目注入用）
    ├── doa-ppt/          (SKILL.md + 2 模板)
    ├── doa-metting/      (SKILL.md + 1 模板)
    ├── doa-apidoc/       (SKILL.md + 2 模板)
    ├── doa-image/        (SKILL.md)
    ├── doa-quotation/    (SKILL.md + 3 模板)
    ├── doa-testreport/   (SKILL.md)
    ├── doa-e2etest/      (SKILL.md + 3 参考文档)
    ├── doa-harness/      (SKILL.md + 5 模板)
    ├── spec-flow-main/   (SKILL.md + 模板 + 参考 + 脚本)
    ├── brainstorming/    (SKILL.md)
    ├── frontend-design/  (SKILL.md)
    └── ui-ux-pro-max/    (SKILL.md + data + scripts)

项目级注入机制

初始化项目时，WorkCopilot 会自动将 Agent、Skill、Hook 和 Prompt 注入到项目目录：

{project-root}/
├── .github/
│   ├── hooks/                 ← 从 embedded-hooks/ 注入
│   │   ├── update-workcopilot.json
│   │   └── scripts/
│   │       └── check-workcopilot.ps1
│   └── prompts/               ← 从 embedded-prompts/ 注入
│       ├── code-review.prompt.md
│       └── generate-tests.prompt.md
└── .claude/
    ├── agents/                ← 从 embedded-agents/ 注入
    │   ├── requirements-analyst.md
    │   ├── system-architect.md
    │   ├── backend-engineer.md
    │   ├── frontend-engineer.md
    │   ├── test-engineer.md
    │   └── mermaid-diagram.md
    └── skills/                ← 从 embedded-skills/ 注入
        ├── doa-ppt/
        ├── doa-metting/
        ├── doa-apidoc/
        ├── doa-image/
        ├── doa-quotation/
        ├── doa-e2etest/
        ├── doa-harness/
        ├── doa-testreport/
        ├── spec-flow-main/
        ├── brainstorming/
        ├── frontend-design/
        └── ui-ux-pro-max/

优先级规则：项目级 .claude/ > 用户级 ~/.claude/。 当项目目录和用户目录下存在同名 Agent 或 Skill 时，优先使用项目里的版本。 这意味着团队可以对项目级的 Agent/Skill 做定制化修改，不会受到个人配置的干扰。

编排资源清单

Agent 矩阵

读取 references/agents.md 获取精简角色定义（调度用摘要），完整版位于 embedded-agents/ 目录。

Agent	角色	调度时机	核心职责
requirements-analyst	需求分析师	Phase 2	业务拆解→EARS 需求→验收标准
system-architect	系统架构师	Phase 3	架构设计→API 设计→数据建模
backend-engineer	后端工程师	Phase 5	API 实现→数据库→认证→安全
frontend-engineer	前端工程师	Phase 5	组件设计→状态管理→路由→UI
test-engineer	测试工程师	Phase 5	测试策略→自动化→覆盖率
mermaid-diagram	时序图架构师	Phase 3	交互流程→Mermaid 时序图

Agent 调度方式：使用 runSubagent 调度对应 Agent，并在 prompt 中注入 references/agents.md 中该 Agent 的角色定义作为系统提示。

Skill 工具箱

以下 Skill 的核心工作流已内置，无需额外安装即可使用：

Skill	用途	调度时机	内置位置
harness	搭建工程轨道	老项目首步 / 新项目收尾	embedded-harness.md
spec-flow	结构化需求-设计-任务流	新代码项目 Phase 2-4	embedded-spec-flow.md
brainstorming	创意探索与需求澄清	任何创作性工作之前	embedded-skills/brainstorming/
frontend-design	高质量前端界面设计	Phase 5 / 按需	embedded-skills/frontend-design/
ui-ux-pro-max	UI/UX 专业设计系统	Phase 5 / 按需	embedded-skills/ui-ux-pro-max/

以下 Skill 已内嵌在 embedded-skills/ 中，项目初始化时自动注入，按需调度：

Skill	用途	调度时机
doa-ppt	生成方案PPT	按需
doa-metting	生成会议纪要	按需
doa-apidoc	生成接口文档	Phase 3 后
doa-image	生成可视化页面	按需
doa-quotation	生成报价单	按需
doa-testreport	基于截图生成测试报告（HTML/PDF/Excel）	按需
doa-e2etest	Playwright E2E 测试全流程 → HTML/PDF 报告	Phase 5.5 / 按需

---

主工作流

调用 WorkCopilot
  → Step 0: 项目类型判定（新 / 老）
  ┌─ 老项目路线 ──────────────────────────────────────┐
  │ → Step E1: 运行 Harness（探测 + 生成工程轨道）       │
  │ → Step E2: 生成/更新 docs/README.md                   │
  │ → Step E3: 注入项目级 Agent & Skill & Hook（6+12+1）          │
  │ → Step E4: 输出 Day-1 验证 & 可用命令清单            │
  │ → Step E5: 状态持久化 + 初始化项目记忆               │
  └──────────────────────────────────────────────────────┘
  ┌─ 新项目路线 ──────────────────────────────────────────┐
  │ → Step N1: 项目子类型判定（代码 / 非代码）             │
  │   ┌─ 非代码项目 ─────────────────────────────────────┐│
  │   │ → 运行 Harness（生成工程轨道）                    ││
  │   │ → 引导选择合适 Skill（PPT/文档/报价/图片等）      ││
  │   │ → 调度 Skill 执行，产出存入 output/{名称}/        ││
  │   │ → 状态持久化（state.json + changelog.md）         ││
  │   └──────────────────────────────────────────────────┘│
  │   ┌─ 代码项目 ───────────────────────────────────────┐│
  │   │ → Phase 1: 技术栈 + 规模 + CI/CD + 环境选型      ││
  │   │ → Phase 2-4: 委托 spec-flow-main skill           ││
  │   │   （需求分析/系统设计/任务拆解，可跳过/可导入）    ││
  │   │ → Phase 5: 脚手架搭建（支持完整/空项目模式）       ││
  │   │   ├── 5.0 脚手架模式判定 + 参考图导入             ││
  │   │   ├── 5.1 后端（完整/空项目 + 多模块/微服务）     ││
  │   │   ├── 5.2 前端（完整/空项目 + 可导入参考图）      ││
  │   │   ├── 5.3 数据库                                  ││
  │   │   ├── 5.4 Docker                                  ││
  │   │   ├── 5.5 测试框架                                ││
  │   │   ├── 5.6 Git 初始化                              ││
  │   │   ├── 5.7 CI/CD 管线                              ││
  │   │   ├── 5.8 多环境配置                              ││
  │   │   └── 5.9 安全基线                                ││
  │   │ → Phase 6: 工程轨道（Harness）                     ││
  │   │ → Phase 6.5: 注入项目级 Agent & Skill & Hook             ││
  │   │ → Phase 7: Day-1 验证                             ││
  │   │ → Phase 8: 项目状态持久化                         ││
  │   │ → Phase 9: 迭代开发（持续循环入口）↺              ││
  │   └──────────────────────────────────────────────────┘│
  └───────────────────────────────────────────────────────┘
  ┌─ 迭代入口（已初始化项目再次调用）──────────────────────┐
  │ → 检测 .workcopilot/state.json                        │
  │ → 自动跳过初始化，直接进入 Phase 9 迭代开发            │
  └───────────────────────────────────────────────────────┘

---

Step 0: 项目类型判定

前置检查：先检测当前工作区是否存在 .workcopilot/state.json。

如存在：

• 读取 source 字段判断来源（"existing" 老项目 / "non-code" 非代码项目 / 无则为新代码项目）
• 如果是非代码项目（source: "non-code"），直接询问用户本次要做什么（复用非代码项目 Q2 选项），调度对应 Skill，完成后追加迭代记录
• 检查初始化阶段是否全部完成（新项目: phase1-7 / 老项目: E1-E4）
• 如全部完成，直接跳转 Phase 9 迭代开发模式，不再询问项目类型
• 如有未完成阶段，提示用户是否继续未完成的初始化
• 同时加载 .workcopilot/decisions.md 和 .workcopilot/tech-debt.md 作为上下文

如不存在，使用 vscode_askQuestions 交互：

Q1: 项目类型
  - "🆕 新创建的项目" (recommended)
  - "📂 已存在的老项目"

如果参数中已含 new 或 existing，跳过交互直接进入对应路线。

---

老项目路线

Step E1: 运行 Harness 工程轨道

读取 references/embedded-harness.md 获取完整流程，执行探测-确认-生成流程。 如 harness 文件已存在，自动切换到增量更新模式。

同时执行代码质量快速扫描：

• 是否存在测试文件 / 测试框架
• 是否配置了 lint / formatter
• 是否存在 CI/CD 配置
• 是否存在 .gitignore

扫描结果纳入 docs/README.md 的“待改进项”段落。

Step E2: 生成/更新 docs/README.md

基于 harness 探测到的项目信息，生成或更新 docs/README.md：

README 结构：

# {项目名称}

{用户在 harness Step 2 输入的项目描述}

## 技术栈

{从 harness 探测结果填充，按子项目分段}

## 快速开始

### 环境要求
{根据技术栈列出 Node/dotnet/Python 版本要求}

### 安装 & 运行
{根据包管理器和框架生成具体命令}

## 项目结构

{从 AGENTS.md 模块地图提炼，简化展示}

## 开发规范

- 工程轨道：`.github/copilot-instructions.md`
- Agent 约束：`.github/AGENTS.md`
- 编码规则：`docs/rules/*.md`
- 验证命令：参见 `.vscode/tasks.json`

如果 docs/README.md 已存在：

1. 读取现有内容
2. 仅更新技术栈、快速开始、项目结构段落
3. 保留用户自定义段落（如 License、Contributing 等）

注意：项目根目录的 README.md 不做任何修改，WorkCopilot 的文档统一放在 docs/ 目录。

Step E3: 注入项目级 Agent、Skill、Hook & Prompt

将内嵌的 Agent、Skill、PreToolUse Hook 和 Prompt 注入到项目目录，使其成为项目级配置。

执行操作：

1. 在项目根目录创建 .claude/agents/ 和 .claude/skills/ 目录
2. 复制 embedded-agents/ 下的 6 个 Agent 文件 → {project}/.claude/agents/
3. 复制 embedded-skills/ 下的 12 个 Skill 目录 → {project}/.claude/skills/
4. 复制 embedded-hooks/ 下的 Hook 配置 → {project}/.github/hooks/
   - update-workcopilot.json → .github/hooks/
   - scripts/check-workcopilot.ps1 → .github/hooks/scripts/
5. 复制 embedded-prompts/ 下的 Prompt 文件 → {project}/.github/prompts/
   - code-review.prompt.md → .github/prompts/
   - generate-tests.prompt.md → .github/prompts/
6. 如果目标位置已存在同名文件，询问用户是否覆盖

Hook 说明：check-workcopilot.ps1 是 PreToolUse 拦截脚本，在执行 git commit/push、dotnet build/publish、docker build 前自动检查 .workcopilot/changelog.md 是否已更新。如未更新，将阻止操作并提示先执行会话持久化。

Prompt 说明：code-review.prompt.md 和 generate-tests.prompt.md 注入到 .github/prompts/，团队成员在 Chat 中输入 / 即可调用全面 Code Review 或生成 xUnit 单元测试。

注入后项目结构：

{project}/
├── .github/
│   ├── hooks/
│   │   ├── update-workcopilot.json
│   │   └── scripts/
│   │       └── check-workcopilot.ps1
│   └── prompts/
│       ├── code-review.prompt.md
│       └── generate-tests.prompt.md
└── .claude/
    ├── agents/
    │   ├── requirements-analyst.md
    │   ├── system-architect.md
    │   ├── backend-engineer.md
    │   ├── frontend-engineer.md
    │   ├── test-engineer.md
    │   └── mermaid-diagram.md
    └── skills/
        ├── doa-ppt/
        ├── doa-metting/
        ├── doa-apidoc/
        ├── doa-image/
        ├── doa-quotation/
        ├── doa-e2etest/
        ├── doa-harness/
        ├── spec-flow-main/
        ├── brainstorming/
        ├── frontend-design/
        └── ui-ux-pro-max/

优先级：项目级 .claude/ > 用户级 ~/.claude/。团队成员本地的同名 Agent/Skill 不会干扰项目。

Step E4: 输出验证 & 命令清单

输出：

1. harness Day-1 验证指令
2. 已注入的 Agent（6个）& Skill（12个）清单
3. 可用 Skill 操作提醒（PPT/会议纪要/接口文档/报价/E2E测试/脑暴/结构化需求等）

Step E5: 老项目状态持久化

老项目完成 E1-E4 后，同样生成 .workcopilot/state.json，使后续调用可进入迭代模式。

{
  "version": "1.0",
  "source": "existing",
  "createdAt": "...",
  "updatedAt": "...",
  "project": {
    "name": "{从 harness 探测到的项目名}",
    "description": "{用户在 E1 输入的描述}",
    "detectedStack": {
      "backend": "dotnet | python | node | other",
      "frontend": "react | vue | angular | h5 | other",
      "database": "sqlserver | postgresql | mysql | other"
    }
  },
  "phases": {
    "E1": { "status": "completed", "completedAt": "..." },
    "E2": { "status": "completed", "completedAt": "..." },
    "E3": { "status": "completed", "completedAt": "..." },
    "E4": { "status": "completed", "completedAt": "..." }
  },
  "iterations": [],
  "services": []
}

同时初始化项目记忆文件（同 Phase 8.1）：

• .workcopilot/decisions.md（空模板）
• .workcopilot/tech-debt.md（空模板，可从 E1 扫描结果中预填已知问题）
• .workcopilot/changelog.md（空模板）

E1 扫描结果转化：如果 E1 代码质量扫描发现缺少测试框架、缺少 lint 等问题，自动写入 tech-debt.md 作为初始技术债记录。

---

新项目路线

Step N1: 项目子类型判定

使用 vscode_askQuestions：

Q1: 项目子类型
  - "💻 代码项目（Web应用/API/系统）" (recommended)
  - "📄 非代码项目（PPT/文档/报价/设计稿）"

非代码项目分流

如果选择非代码项目，进一步询问：

Q2: 要做什么？
  - "📊 PPT / 方案演示" → 调用 doa-ppt
  - "📋 会议纪要" → 调用 doa-metting
  - "💰 项目报价" → 调用 doa-quotation
  - "📝 接口文档" → 调用 doa-apidoc
  - "🎨 可视化页面/长图" → 调用 doa-image
  - "📄 Word 文档" → 调用 docx skill
  - "🖼️ 前端设计稿" → 调用 frontend-design

非代码项目 Harness 工程轨道

非代码项目在调度 Skill 之前，先运行 Harness 生成工程轨道（同老项目 Step E1 逻辑）：

读取 references/embedded-harness.md 执行探测-确认-生成流程，生成：

• .github/copilot-instructions.md
• .github/AGENTS.md
• CODEOWNERS

简化规则：非代码项目不生成 .vscode/tasks.json 和 docs/rules/*.md（无代码构建/测试需求）。如 harness 文件已存在，自动跳过。

非代码项目产出目录约定

所有非代码项目的产出文件（PPT、Excel、PDF、Word、图片等）统一存放在 output/ 目录下，按产出名称建立子文件夹：

{project-root}/
└── output/
    ├── {产出名称A}/              # 如 "Q3季度汇报PPT"
    │   ├── Q3季度汇报.pptx
    │   └── generate_ppt.py       # 生成脚本（如有）
    ├── {产出名称B}/              # 如 "项目报价单"
    │   ├── 报价单_v1.xlsx
    │   └── generate_quotation.py
    └── {产出名称C}/              # 如 "API接口文档"
        ├── 接口说明书.pdf
        └── generate_apidoc.py

命名规则：

• 子文件夹名称 = 用户描述的产出名称（中文或英文均可），简洁明了
• 如用户未指定名称，使用 vscode_askQuestions 询问
• 生成脚本（Python 等中间文件）与最终产出放在同一子文件夹内
• 同一产出的多个版本用 _v1、_v2 后缀区分

调度 Skill 时的产出路径传递：

• 调用对应 Skill 前，先创建 output/{产出名称}/ 目录
• 在 Skill 调度的 prompt 中明确指定产出输出路径为 output/{产出名称}/
• 确保 Skill 生成的所有文件都写入该目录

选择后调度对应 Skill 执行，产出文件存入 output/{产出名称}/。

非代码项目状态持久化

非代码项目完成后，同样生成 .workcopilot/state.json 及记忆文件，确保项目记忆一致性。

执行操作：

1. 使用 vscode_askQuestions 收集项目名称和描述（如尚未收集）
2. 创建 .workcopilot/ 目录及以下文件：

// .workcopilot/state.json
{
  "version": "1.0",
  "source": "non-code",
  "timezone": "Asia/Shanghai",
  "createdAt": "...",
  "updatedAt": "...",
  "project": {
    "name": "{项目名}",
    "description": "{项目描述}",
    "type": "non-code",
    "skill": "doa-ppt | doa-metting | doa-quotation | doa-apidoc | doa-image | docx | frontend-design"
  },
  "outputs": [
    {
      "name": "{产出名称}",
      "skill": "doa-ppt",
      "path": "output/{产出名称}/",
      "createdAt": "..."
    }
  ],
  "iterations": [
    {
      "id": "iter-001",
      "date": "...",
      "scope": "{首次调度的 Skill 及产出摘要}"
    }
  ]
}

3. 初始化记忆文件：
   • .workcopilot/decisions.md（空模板）
   • .workcopilot/changelog.md（记录首次产出）

后续调用：非代码项目再次调用 WorkCopilot 时，检测到 source: "non-code"，直接询问用户本次要做什么（复用上方 Q2 选项），新产出继续存入 output/{新产出名称}/，并在完成后追加 outputs 数组和迭代记录到 state.json 和 changelog.md。Harness 已存在则自动跳过。

---

代码项目 Phase 1: 技术栈选型

使用 vscode_askQuestions 一次性收集：

Q1: 项目名称
  [自由输入]

Q2: 一句话描述项目
  [自由输入]

Q3: 后端技术栈
  - ".NET 8 (WebAPI + SqlSugar)" (recommended)
  - ".NET 8 (WebAPI + EF Core)"
  - "Python (FastAPI + SQLAlchemy)"
  - "其他（请说明）"

Q4: 前端技术栈
  - "React + TypeScript + Ant Design" (recommended)
  - "纯 HTML5 + CSS + JS (轻量级)"
  - "其他（请说明）"

Q5: 数据库
  - "SQL Server" (recommended)
  - "PostgreSQL"
  - "MySQL"
  - "SQLite (开发/轻量)"
  - "其他（请说明）"

Q6: 认证方式
  - "JWT Token 认证" (recommended)
  - "Azure AD / Entra ID"
  - "Cookie Session"
  - "暂不需要"

Q7: 是否需要 Docker 支持
  - "是" (recommended)
  - "否"

Q8: 项目规模 & 架构
  - "🏠 单体应用（单后端 + 单前端）" (recommended)
  - "📦 多模块单体（共享代码库，多个功能模块）"
  - "🔗 微服务架构（多个独立后端服务 + API 网关）"

Q9: CI/CD 管线
  - "GitHub Actions" (recommended)
  - "Azure DevOps Pipelines"
  - "暂不配置"

Q10: 多环境配置
  - "dev + prod（两套环境）" (recommended)
  - "dev + staging + prod（三套环境）"
  - "仅 dev（开发环境）"

Q-scaffold: 脚手架生成模式
  header: "后端和前端分别选择脚手架模式"

  Q-scaffold-backend: 后端脚手架模式
    - "🏗️ 完整脚手架（包含业务代码骨架 + 示例）" (recommended)
    - "📦 空项目（仅项目结构 + 基础配置，不含业务代码）"

  Q-scaffold-frontend: 前端脚手架模式
    - "🏗️ 完整脚手架（包含页面骨架 + 路由 + 状态管理）" (recommended)
    - "📦 空项目（仅项目结构 + 基础配置，不含页面代码）"
    - "🖼️ 完整脚手架 + 参考设计图（导入 UI 参考图辅助生成）"

规模说明：

• 单体应用：适合中小型项目，一个后端 + 一个前端，快速启动
• 多模块单体：适合中大型项目，单个解决方案内按模块拆分（.NET Multi-Project / Python Package），共享数据库
• 微服务架构：适合大型项目，每个服务独立部署、独立数据库，通过 API 网关统一入口

收集完成后，将信息汇总为 project-config 数据结构，供后续 Phase 使用：

project:
  name: "{项目名}"
  description: "{项目描述}"
  backend:
    stack: "dotnet" | "python"
    framework: "webapi" | "fastapi"
    orm: "sqlsugar" | "efcore" | "sqlalchemy"
  frontend:
    stack: "react" | "h5"
    ui: "antd" | "none"
  database: "sqlserver" | "postgresql" | "mysql" | "sqlite"
  auth: "jwt" | "azure-ad" | "cookie" | "none"
  docker: true | false
  scale: "monolith" | "modular" | "microservice"
  cicd: "github-actions" | "azure-devops" | "none"
  environments: "dev-prod" | "dev-staging-prod" | "dev-only"
  docs: "generate" | "import" | "skip"
  scaffold:
    backend: "full" | "empty"
    frontend: "full" | "empty" | "full-with-ref-image"
    ref_image: "{path}" | null      # 前端参考设计图路径（仅 full-with-ref-image 时有值）

---

代码项目 Phase 2-4 前置：文档策略判定

Phase 2（需求分析）、Phase 3（系统设计）、Phase 4（任务拆解）均支持三种模式：

使用 vscode_askQuestions 询问：

Q11: 需求 & 设计文档策略
  - "📝 AI 生成（逐阶段引导生成需求/设计/任务文档）" (recommended)
  - "📂 我有现成资料（上传或粘贴，AI 整理为标准格式）"
  - "⏭️ 跳过（直接进入脚手架搭建，后续按需补充）"

模式说明

模式	行为	适用场景
AI 生成	按原流程逐阶段引导生成 proposal → requirements → design → tasks	从零开始的新项目
导入现有资料	用户提供需求文档/PRD/设计稿/会议纪要等，AI 整理为标准格式写入 .spec-flow/	已有产品经理或客户提供的资料
跳过	Phase 2-4 全部跳过，直接进入 Phase 5 脚手架搭建	快速原型、已有明确方案

导入模式流程

当用户选择"我有现成资料"时：

1. 提示用户提供资料（支持以下方式）：
   - 直接在对话中粘贴文本
   - 指定工作区中的文件路径（.md / .docx / .pdf / .txt）
   - 提供多份资料，逐份处理

2. AI 读取并分析资料内容

3. 调用 spec-flow-main skill，将资料作为输入：
   - spec-flow 自动按其标准格式在 .spec-flow/active/{project-name}/ 下
     生成 proposal.md、requirements.md、design.md、tasks.md
   - WorkCopilot 不自行创建这些文件，完全复用 spec-flow 的产出

4. 展示整理结果摘要，用户确认或修改

提示：导入模式下，如果用户资料只覆盖部分阶段（如只有需求没有设计），AI 会对已有部分做整理，缺失部分询问用户是"AI 补充生成"还是"暂时跳过"。

跳过模式

跳过后：

• Phase 2-4 状态标记为 skipped（写入 state.json）
• 直接进入 Phase 5 脚手架搭建
• 后续可通过 Phase 9 迭代开发中选择"补充需求/设计文档"来补做

---

代码项目 Phase 2: 需求分析

前置条件：仅在文档策略选择"AI 生成"时执行。"导入"模式在上方统一处理，"跳过"模式直接进入 Phase 5。

委托 Skill: spec-flow-main

直接调用 spec-flow-main skill 的 Phase 1-2 流程，由 spec-flow 在 .spec-flow/active/{project-name}/ 下生成 proposal.md 和 requirements.md。

WorkCopilot 不自行定义文档结构，完全复用 spec-flow 的文档格式和交互流程。

⏸️ 阶段确认：spec-flow 会在每个阶段完成后自动请求用户确认。

---

代码项目 Phase 3: 系统设计

前置条件：仅在文档策略选择"AI 生成"时执行。

委托 Skill: spec-flow-main

直接调用 spec-flow-main skill 的 Phase 3 流程，由 spec-flow 在 .spec-flow/active/{project-name}/ 下生成 design.md。

WorkCopilot 不自行定义文档结构，完全复用 spec-flow 的设计文档格式和交互流程。

上下文传递：将 Phase 1 的技术选型（project-config）作为上下文传递给 spec-flow，确保设计文档与技术栈选型一致。

⏸️ 阶段确认：spec-flow 会在阶段完成后自动请求用户确认。

---

代码项目 Phase 4: 任务拆解

前置条件：仅在文档策略选择"AI 生成"时执行。

委托 Skill: spec-flow-main

调用 spec-flow-main skill 的 Phase 4 流程，由 spec-flow 在 .spec-flow/active/{project-name}/ 下生成 tasks.md。WorkCopilot 在 spec-flow 生成的基础上，补充以下增强信息：

4.1 任务分组与拆解

按以下阶段拆解任务，每阶段对应一个里程碑：

里程碑 M1: 基础设施搭建（Sprint 1）
  T-001: 创建后端项目结构          [Low]  [4h]  backend-engineer
  T-002: 创建前端项目结构          [Low]  [4h]  frontend-engineer
  T-003: 配置数据库连接            [Med]  [4h]  backend-engineer
  T-004: 搭建认证模块              [Med]  [8h]  backend-engineer
  T-005: 配置 Docker（如需）       [Low]  [4h]  backend-engineer

里程碑 M2: 核心功能开发（Sprint 2-N）
  T-00x: （根据需求文档 FR 列表生成，每个 FR 至少拆为 1 个任务）

里程碑 M3: 集成 & 测试（Sprint N+1）
  T-0xx: 单元测试                  [Med]  [8h]  test-engineer
  T-0xx: 集成测试                  [High] [8h]  test-engineer
  T-0xx: 端到端测试                [High] [8h]  test-engineer

里程碑 M4: 文档 & 部署（Sprint N+2）
  T-0xx: API 文档                  [Low]  [4h]  backend-engineer
  T-0xx: 部署配置                  [Med]  [4h]  backend-engineer

4.2 任务卡片结构

每个任务包含以下字段：

### T-001: {任务标题}
- **里程碑**：M1 基础设施搭建
- **Sprint**：Sprint 1
- **复杂度**：Low / Medium / High
- **预估工时**：4h / 8h / 16h / 24h
- **Agent**：backend-engineer / frontend-engineer / test-engineer
- **文件**：`src/Controllers/...`, `src/Services/...`
- **依赖**：无 / T-003, T-004
- **验收标准**：AC-001（关联 requirements.md）
- **状态**：⏳ 待开始

4.3 关键路径分析

任务拆解完成后，自动分析并标注关键路径：

## 关键路径

T-001 → T-003 → T-004 → T-010（首个核心功能）→ T-020（集成测试）

⏱️ 关键路径总工时：48h
📅 预计总工期：{根据工时 ÷ 每日有效编码时间 6h 估算}

⚠️ 瓶颈任务：T-004（认证模块），阻塞所有需要鉴权的后续任务

4.4 任务汇总表

在 tasks.md 末尾生成汇总：

## 📊 汇总

| 里程碑 | 任务数 | 总工时 | 建议 Sprint |
|--------|-------|--------|------------|
| M1 基础设施 | 5 | 24h | Sprint 1 |
| M2 核心功能 | {n} | {x}h | Sprint 2-{n} |
| M3 测试 | {n} | {x}h | Sprint {n+1} |
| M4 文档部署 | {n} | {x}h | Sprint {n+2} |
| **合计** | **{total}** | **{total}h** | **{sprints} 个 Sprint** |

按 Agent 分配：
| Agent | 任务数 | 工时 |
|-------|-------|------|
| backend-engineer | {n} | {x}h |
| frontend-engineer | {n} | {x}h |
| test-engineer | {n} | {x}h |

工时估算原则：

• Low 复杂度：4h（半天）
• Medium 复杂度：8h（1 天）
• High 复杂度：16-24h（2-3 天）
• 一个 Sprint = 5 个工作日 = 40h 有效编码时间（按每日 8h × 有效率 80% ≈ 6h 估算）

⏸️ 阶段确认：展示任务清单和关键路径，等待用户确认后继续。

---

代码项目 Phase 5: 脚手架搭建

根据 Phase 1 技术选型，调度对应 Agent 创建项目骨架。

规模感知：Phase 5 的产出结构取决于 Phase 1 的 scale 选项：

• monolith → 标准单体结构（下方 5.1 默认方案）
• modular → 多模块单体（见 5.1.1）
• microservice → 微服务架构（见 5.1.2）

5.0 脚手架模式判定 & 参考图导入

根据 Phase 1 Q-scaffold 的选择，决定后端/前端各自的生成策略：

模式	后端产出	前端产出
完整脚手架	项目结构 + 业务代码骨架 + 示例接口 + 中间件 + 测试	项目结构 + 页面骨架 + 路由 + 状态管理 + Layout
空项目	项目结构 + 基础配置（入口文件 + 依赖声明 + .gitignore），不含业务代码	项目结构 + 基础配置（入口文件 + 依赖声明），不含页面代码
完整 + 参考图	—	同完整脚手架，但参考设计图辅助生成 UI 布局

前端参考设计图导入

当前端选择「完整脚手架 + 参考设计图」时：

1. 使用 vscode_askQuestions 请用户提供参考图：
   - 提示用户将设计图/截图/原型图放入项目目录（如 docs/design-refs/）
   - 支持格式：PNG / JPG / JPEG / WEBP
   - 可提供多张图（不同页面/模块各一张）

2. 使用 view_image 逐张读取参考图，分析并提取：
   - 页面布局结构（Header / Sidebar / Content / Footer）
   - 色彩方案（主色/辅助色/背景色/文字色）
   - 组件类型识别（表格/表单/卡片/图表/导航）
   - 页面数量与导航结构

3. 将分析结果保存为 docs/design-refs/analysis.md：
   ```markdown
   # 参考设计图分析

   ## 页面清单
   | 页面 | 参考图 | 布局类型 | 核心组件 |
   |------|--------|---------|----------|
   | 首页 | home.png | 侧边栏布局 | 数据卡片 ×4, 折线图, 表格 |
   | ... |

   ## 色彩方案
   - 主色：#1890FF
   - 辅助色：...

   ## 布局模式
   - 整体布局：左侧边栏 + 顶部导航 + 内容区
   - 响应式：...

4. 在 5.2 前端脚手架生成时，将 analysis.md 作为上下文传递给 frontend-engineer：
   • 页面结构参照参考图布局
   • 配色方案与参考图保持一致
   • 组件选型匹配参考图中识别到的类型

> **注意**：参考图仅作为 UI 风格和布局的参考，不会 1:1 像素级复制。AI 会根据参考图风格 + Ant Design 组件库生成符合设计意图的代码。

##### 空项目模式说明

选择空项目模式时，后端/前端仅生成最小化可运行的项目结构：

**后端空项目**（.NET 示例）：

backend/ ├── src/ │ └── {ProjectName}.Api/ │ ├── Program.cs # 最小 Minimal API 入口（仅健康检查端点） │ ├── appsettings.json │ ├── appsettings.Development.json │ └── {ProjectName}.Api.csproj ├── {ProjectName}.sln ├── .editorconfig └── Directory.Build.props

**后端空项目**（Python 示例）：

backend/ ├── app/ │ ├── init.py │ └── main.py # 最小 FastAPI 入口（仅健康检查端点） ├── requirements.txt ├── pyproject.toml └── .env.example

**前端空项目**（React 示例）：

frontend/ ├── src/ │ ├── main.tsx # 入口 │ ├── App.tsx # 空白根组件 │ └── vite-env.d.ts ├── index.html ├── package.json ├── tsconfig.json ├── vite.config.ts └── .eslintrc.cjs

**前端空项目**（H5 示例）：

frontend/ ├── index.html # 空白 HTML 骨架 ├── css/ │ └── style.css ├── js/ │ └── app.js └── assets/

> **空项目后续补充**：在 Phase 9 迭代开发中选择「新增功能模块」时，根据需求逐步添加业务代码。适合需求尚不明确或想边做边定义的项目。

#### 5.1 后端脚手架

**调度 Agent**: `backend-engineer`

> **模式判定**：当 `scaffold.backend = "empty"` 时，仅生成上方「空项目模式」中的最小结构，跳过下方的完整脚手架内容，直接进入 5.2。

##### .NET 方案（推荐）

读取 [references/dotnet-scaffold.md](./references/dotnet-scaffold.md) 获取完整模板。

项目结构：

backend/ ├── src/ │ └── {ProjectName}.Api/ │ ├── Program.cs # Minimal API 入口 │ ├── appsettings.json # 配置文件 │ ├── appsettings.Development.json │ ├── Controllers/ # API 控制器 │ │ └── HealthController.cs # 健康检查 │ ├── Services/ # 业务服务层 │ ├── Repositories/ # 数据访问层 │ ├── Models/ # 实体模型 │ │ └── Entities/ │ ├── DTOs/ # 数据传输对象 │ ├── Infrastructure/ # 基础设施 │ │ ├── Auth/ # 认证模块 │ │ ├── Database/ # SqlSugar 配置 │ │ ├── Middleware/ # 中间件 │ │ └── Extensions/ # 服务扩展 │ └── {ProjectName}.Api.csproj ├── tests/ │ └── {ProjectName}.Tests/ │ ├── {ProjectName}.Tests.csproj │ └── Controllers/ ├── {ProjectName}.sln ├── .editorconfig ├── Directory.Build.props └── Dockerfile (如需)

核心功能：
- 统一异常处理中间件
- JWT / Azure AD 认证配置
- SqlSugar ORM 配置 + Code First 就绪
- Swagger/OpenAPI 文档
- 健康检查端点
- CORS 配置
- Serilog 日志

##### Python 备选方案

项目结构：

backend/ ├── app/ │ ├── init.py │ ├── main.py # FastAPI 入口 │ ├── core/ │ │ ├── config.py # 配置管理 │ │ ├── security.py # 认证模块 │ │ └── database.py # 数据库连接 │ ├── api/ │ │ └── v1/ │ │ ├── endpoints/ # API 路由 │ │ └── deps.py # 依赖注入 │ ├── models/ # SQLAlchemy 模型 │ ├── schemas/ # Pydantic Schema │ ├── services/ # 业务逻辑 │ └── repositories/ # 数据访问 ├── tests/ ├── alembic/ # 数据库迁移 ├── requirements.txt ├── pyproject.toml ├── Dockerfile (如需) └── .env.example

##### 5.1.1 多模块变体（scale = modular）

当项目选择多模块单体时，在单体结构基础上扩展为多项目/多 Package 结构：

**.NET 多模块**：

backend/ ├── src/ │ ├── {ProjectName}.Api/ # API 入口（网关层） │ ├── {ProjectName}.Core/ # 核心业务逻辑（共享） │ │ ├── Interfaces/ # 服务接口定义 │ │ ├── Entities/ # 领域实体 │ │ └── DTOs/ # 共享 DTO │ ├── {ProjectName}.Module.{ModuleA}/ # 功能模块 A │ │ ├── Controllers/ │ │ ├── Services/ │ │ └── Repositories/ │ ├── {ProjectName}.Module.{ModuleB}/ # 功能模块 B │ └── {ProjectName}.Infrastructure/ # 基础设施（数据库/缓存/消息） ├── tests/ │ ├── {ProjectName}.Core.Tests/ │ ├── {ProjectName}.Module.{ModuleA}.Tests/ │ └── {ProjectName}.Module.{ModuleB}.Tests/ ├── {ProjectName}.sln └── Directory.Build.props # 统一版本管理

**Python 多模块**：

backend/ ├── app/ │ ├── main.py │ ├── core/ # 共享核心 │ │ ├── config.py │ │ ├── security.py │ │ ├── database.py │ │ └── shared_schemas.py # 共享 Schema │ ├── modules/ │ │ ├── {module_a}/ # 功能模块 A │ │ │ ├── router.py │ │ │ ├── service.py │ │ │ ├── models.py │ │ │ └── schemas.py │ │ └── {module_b}/ # 功能模块 B │ └── infrastructure/ # 基础设施 ├── tests/ │ ├── test_{module_a}/ │ └── test_{module_b}/ └── pyproject.toml

> **模块拆分依据**：根据 Phase 2 需求分析的领域边界自动建议模块划分。用户可在 Phase 4 任务拆解时调整。

##### 5.1.2 微服务变体（scale = microservice）

当项目选择微服务架构时，每个服务独立项目、独立数据库、通过 API 网关统一入口。

**整体 Monorepo 结构**：

{project-root}/ ├── backend/ │ ├── services/ │ │ ├── gateway/ # API 网关（YARP/.NET 或 Kong） │ │ │ ├── src/ │ │ │ ├── Dockerfile │ │ │ └── README.md │ │ ├── {service-a}/ # 业务服务 A │ │ │ ├── src/ │ │ │ ├── tests/ │ │ │ ├── Dockerfile │ │ │ └── README.md │ │ └── {service-b}/ # 业务服务 B │ ├── shared/ │ │ └── {ProjectName}.Contracts/ # 共享契约（DTO/事件/接口） │ └── {ProjectName}.sln # 或 pyproject.toml（全局） ├── frontend/ # 前端 ├── docs/ # 项目文档 ├── infra/ │ ├── docker-compose.yml # 全部服务编排 │ ├── docker-compose.override.yml # 本地开发覆盖 │ └── k8s/ # Kubernetes 部署文件（可选） │ ├── namespace.yaml │ ├── {service-a}-deployment.yaml │ └── {service-b}-deployment.yaml ├── .github/ │ └── workflows/ # 每个服务独立 CI/CD └── README.md

**网关配置**：
- .NET 推荐 YARP（Yet Another Reverse Proxy），自动生成 `yarp.json` 路由配置
- Python 推荐 FastAPI Gateway 模式或独立 Nginx/Kong

**服务间通信**：
- 同步调用：HTTP + 共享契约 DTO（`shared/Contracts/`）
- 异步消息：预留 RabbitMQ / Azure Service Bus 集成点（不强制安装）

**数据库隔离**：
- 每个服务独立数据库 Schema 或独立数据库实例
- docker-compose 中为每个服务配置独立的 DB 连接字符串

> **注意**：微服务脚手架默认只创建 gateway + 2 个占位服务（根据需求文档命名），用户可在后续迭代中增加服务。

#### 5.2 前端脚手架

**调度 Agent**: `frontend-engineer`

> **模式判定**：
> - `scaffold.frontend = "empty"` → 仅生成上方「空项目模式」中的最小结构，跳过下方完整脚手架内容
> - `scaffold.frontend = "full-with-ref-image"` → 先执行 5.0 中的参考图分析，将 `docs/design-refs/analysis.md` 传递给 `frontend-engineer` 作为设计上下文，再按下方完整脚手架流程生成
> - `scaffold.frontend = "full"` → 正常走完整脚手架流程

##### React 方案（推荐）

读取 [references/react-scaffold.md](./references/react-scaffold.md) 获取完整模板。

项目结构：

frontend/ ├── src/ │ ├── main.tsx # 入口 │ ├── App.tsx # 根组件 │ ├── routes/ # 路由配置 │ │ └── index.tsx │ ├── pages/ # 页面 │ │ ├── Login/ │ │ ├── Dashboard/ │ │ └── NotFound/ │ ├── components/ # 通用组件 │ │ └── Layout/ │ ├── hooks/ # 自定义 Hooks │ ├── services/ # API 调用层 │ │ ├── api.ts # Axios 实例 │ │ └── auth.ts # 认证 API │ ├── stores/ # 状态管理 (zustand) │ │ └── useAuthStore.ts │ ├── types/ # TypeScript 类型 │ └── utils/ # 工具函数 ├── public/ ├── index.html ├── package.json ├── tsconfig.json ├── vite.config.ts ├── .eslintrc.cjs └── .prettierrc

核心功能：
- Vite + React 18 + TypeScript
- React Router v6 路由
- Ant Design 组件库
- Axios 请求封装 + 拦截器
- JWT Token 管理（自动刷新）
- zustand 状态管理
- 登录页 + Layout 骨架
- ESLint + Prettier 配置

##### H5 备选方案

轻量级单页面结构：

frontend/ ├── index.html ├── css/ │ └── style.css ├── js/ │ ├── app.js │ ├── api.js # API 调用封装 │ └── auth.js # 认证逻辑 └── assets/

#### 5.3 数据库脚手架

根据后端选型自动生成：

- **.NET + SqlSugar**：生成 `SqlSugarClient` 配置、基础 `Entity`（User 等）、Code First 初始化
- **Python + SQLAlchemy**：生成 `Base` 模型、`User` 模型、Alembic 初始配置

#### 5.4 Docker 支持（如选择）

生成：
- 后端 `Dockerfile`（多阶段构建）
- 前端 `Dockerfile`（Node 构建 + Nginx 托管）
- 各项目 `.dockerignore`
- `docker-compose.yml`（后端 + 前端 + 数据库，含 healthcheck）
- `.env.docker`（环境变量模板，复制为 `.env` 后使用）

> **注意**：docker-compose 中的数据库镜像根据技术栈自动适配：
> - .NET 默认 SQL Server (`mcr.microsoft.com/mssql/server:2022-latest`)
> - Python 默认 PostgreSQL (`postgres:16-alpine`)
> - nginx.conf 中的 `proxy_pass` 端口根据后端自动匹配（.NET → 8080 / Python → 8000）

#### 5.5 测试框架

**调度 Agent**: `test-engineer`

- **.NET**：xUnit + FluentAssertions + Moq
- **Python**：pytest + httpx（AsyncClient）
- **React**：Vitest + React Testing Library
- **H5**：不生成测试框架

#### 5.6 Git 初始化 & .gitignore

在项目根目录执行：
1. 生成 `.gitignore`（根据技术栈组合前后端规则）
2. `git init`
3. `git add .`
4. `git commit -m "chore: initial project scaffold"`

`.gitignore` 核心规则：
- **.NET**：`bin/` `obj/` `.vs/` `*.user` `logs/`
- **Python**：`__pycache__/` `venv/` `.env` `*.pyc`
- **React**：`node_modules/` `dist/` `.env.local`
- **通用**：`.DS_Store` `Thumbs.db` `*.log`

#### 5.7 CI/CD 管线（如选择）

根据 Phase 1 的 `cicd` 选项生成对应管线配置。

##### GitHub Actions

生成 `.github/workflows/ci.yml`：

```yaml
# 触发条件: push 到 main/develop，PR 到 main
# 矩阵策略: 后端构建 + 前端构建 + 测试并行

jobs:
  backend:
    - checkout
    - 安装依赖（dotnet restore / pip install）
    - 编译（dotnet build / 语法检查）
    - 单元测试（dotnet test / pytest）
    - 代码覆盖率报告
  frontend:
    - checkout
    - npm ci
    - lint（eslint）
    - 单元测试（vitest）
    - 构建（vite build）
  docker: (if docker enabled)
    - needs: [backend, frontend]
    - 构建 Docker 镜像
    - 推送到容器注册表（标签: commit SHA + latest）

微服务架构时，为每个服务生成独立 workflow 文件，并添加路径过滤：

on:
  push:
    paths: ['backend/services/{service-name}/**', 'backend/shared/**']

Azure DevOps Pipelines

生成 azure-pipelines.yml，结构同上但使用 Azure Pipelines 语法（stages / jobs / steps）。

5.8 多环境配置

根据 Phase 1 的 environments 选项生成环境配置文件。

后端环境配置

.NET：

appsettings.json                    # 通用配置（不含敏感信息）
appsettings.Development.json        # 开发环境
appsettings.Staging.json            # 预发布环境（如选三套）
appsettings.Production.json         # 生产环境（仅结构，值用环境变量）

Python：

.env.example                        # 环境变量模板（提交到 Git）
.env.development                    # 开发环境
.env.staging                        # 预发布环境（如选三套）
.env.production                     # 生产环境（仅结构，值用环境变量）

前端环境配置

.env                                # 通用
.env.development                    # VITE_API_BASE_URL=http://localhost:8080
.env.staging                        # VITE_API_BASE_URL=https://staging-api.example.com
.env.production                     # VITE_API_BASE_URL=https://api.example.com

Docker 环境隔离

docker-compose.yml                  # 基础定义
docker-compose.override.yml         # 本地开发覆盖（端口映射、卷挂载、热重载）
docker-compose.staging.yml          # 预发布覆盖（如选三套）
docker-compose.prod.yml             # 生产覆盖（资源限制、日志驱动、重启策略）

安全原则：生产环境配置文件只包含 key 名和占位符，实际值通过 CI/CD 的 Secrets / 环境变量注入，绝不提交到 Git。

5.9 安全基线

在脚手架中默认嵌入安全防护措施：

后端安全

项	.NET 实现	Python 实现
安全 Headers	SecurityHeadersMiddleware（X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security）	starlette-security-headers 或自定义中间件
CORS 白名单	仅允许前端域名，禁止 AllowAnyOrigin + AllowCredentials	CORSMiddleware 配置 allow_origins 列表
速率限制	AspNetCoreRateLimit 中间件	slowapi 库
输入验证	FluentValidation / DataAnnotations	Pydantic 模型自动验证
SQL 注入防护	SqlSugar 参数化查询（禁止拼接 SQL）	SQLAlchemy 参数化（禁止 text() 拼接）
敏感数据脱敏	日志中不输出 Password/Token/ConnectionString	同左
依赖漏洞扫描	CI 中添加 dotnet list package --vulnerable	CI 中添加 pip-audit 或 safety check

前端安全

• XSS 防护：React 默认转义 + 禁止 dangerouslySetInnerHTML（规则文件中约束）
• CSP 策略：Nginx 配置 Content-Security-Policy header
• 敏感信息：.env 中仅存放 VITE_ 前缀的公开配置，禁止嵌入 API Key / Secret

安全检查清单（写入 docs/rules/security.md）

生成规则文件供 Harness 和 Agent 引用，确保后续开发持续遵守安全要求。

---

代码项目 Phase 6: 工程轨道

读取 references/embedded-harness.md 获取完整流程。

在项目脚手架创建完成后，运行 Harness 工作流生成完整的工程轨道文件：

• .github/copilot-instructions.md
• .github/AGENTS.md
• .vscode/tasks.json
• CODEOWNERS
• docs/rules/*.md

同时生成/更新 docs/README.md（同老项目 Step E2 逻辑）。

---

代码项目 Phase 6.5: 注入项目级 Agent、Skill、Hook & Prompt

同老项目 Step E3 逻辑，将内嵌的 6 个 Agent、12 个 Skill、PreToolUse Hook 和 2 个 Prompt 复制到项目目录：

1. 创建 {project}/.claude/agents/ 和 {project}/.claude/skills/
2. 复制 embedded-agents/* → .claude/agents/
3. 复制 embedded-skills/* → .claude/skills/
4. 复制 embedded-hooks/* → .github/hooks/（含 scripts/ 子目录）
5. 复制 embedded-prompts/* → .github/prompts/
6. 将 .claude/ 加入 .gitignore 的考量项（提示用户确认）

注入完成后，后续在该项目工作时，所有 Agent 和 Skill 均优先使用项目级版本。 PreToolUse Hook 会在 git commit/push、dotnet build/publish、docker build 前自动拦截，确保 .workcopilot/ 已更新。

提示：团队希望对某个 Agent/Skill 做定制化修改时，直接编辑项目里的版本即可，不影响其他项目。

---

代码项目 Phase 7: Day-1 验证

输出最终交付清单：

📦 项目创建完成！

📂 项目结构:
├── backend/                 ← 后端 (.NET / Python)
├── frontend/                ← 前端 (React / H5)
├── docs/                    ← 项目文档 (README + rules)
├── .claude/                 ← 项目级 Agent & Skill（6+10）
├── docker-compose.yml       ← Docker 编排 (如有)
├── .env.docker              ← Docker 环境变量模板 (如有)
├── .github/                 ← 工程轨道
├── .vscode/tasks.json       ← 验证链
├── .workcopilot/            ← 项目状态 & 记忆
└── .spec-flow/              ← 需求 & 设计文档

🚀 快速启动:
  后端: cd backend && dotnet run --project src/{ProjectName}.Api
  前端: cd frontend && npm install && npm run dev

🐳 Docker 启动 (如有):
  cp .env.docker .env && docker compose up -d
  访问: http://localhost (前端) | http://localhost:8080/swagger (后端API)

✅ 验证命令:
  Ctrl+Shift+P → "Run Task" → "verify"

🛠️ 后续可用 Skill（已注入项目 .claude/skills/）:
  - doa-apidoc   → 生成接口文档
  - doa-ppt      → 生成方案PPT
  - doa-quotation → 生成报价单
  - doa-metting  → 生成会议纪要
  - doa-image    → 生成可视化页面/长图
  - doa-harness  → 更新工程轨道
  - spec-flow-main → 结构化需求-设计-任务流
  - brainstorming → 创意探索与需求澄清
  - frontend-design → 高质量前端界面设计
  - ui-ux-pro-max → UI/UX 专业设计系统

🤖 项目级 Agent（已注入 .claude/agents/，优先于用户级）:
  - requirements-analyst / system-architect / backend-engineer
  - frontend-engineer / test-engineer / mermaid-diagram

---

代码项目 Phase 8: 项目状态持久化

在 Phase 7 完成后，将 project-config 和项目元数据持久化到文件，支持跨会话恢复上下文。

生成 .workcopilot/state.json：

{
  "version": "1.0",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-01T00:00:00Z",
  "project": {
    "name": "{项目名}",
    "description": "{项目描述}",
    "backend": { "stack": "dotnet", "framework": "webapi", "orm": "sqlsugar" },
    "frontend": { "stack": "react", "ui": "antd" },
    "database": "sqlserver",
    "auth": "jwt",
    "docker": true,
    "scale": "monolith",
    "cicd": "github-actions",
    "environments": "dev-staging-prod"
  },
  "phases": {
    "phase1": { "status": "completed", "completedAt": "..." },
    "phase2": { "status": "completed", "completedAt": "..." },
    "phase3": { "status": "completed", "completedAt": "..." },
    "phase4": { "status": "completed", "completedAt": "..." },
    "phase5": { "status": "completed", "completedAt": "..." },
    "phase6": { "status": "completed", "completedAt": "..." },
    "phase7": { "status": "completed", "completedAt": "..." }
  },
  "iterations": [],
  "services": []
}

跨会话恢复：当用户在已有项目中再次调用 WorkCopilot 时：

1. 检查 .workcopilot/state.json 是否存在
2. 如存在，读取项目配置和已完成的阶段
3. 自动跳过已完成的初始化阶段，直接进入迭代开发模式

8.1 项目记忆体系

除 state.json 外，在 .workcopilot/ 目录下维护以下长期记忆文件：

.workcopilot/
├── state.json              ← 项目配置 + 阶段状态 + 迭代记录
├── decisions.md            ← 架构决策记录（ADR）
├── tech-debt.md            ← 技术债 & 已知问题追踪
└── changelog.md            ← 变更日志（自动维护）

decisions.md — 架构决策记录（ADR）

记录项目中的重要技术决策，避免重复讨论。每次做出架构性选择时追加：

# 架构决策记录

## ADR-001: 选择 SqlSugar 作为 ORM
- **日期**：2025-01-01
- **状态**：已采纳
- **背景**：需要一个轻量级 ORM，支持 Code First 和多数据库
- **决策**：使用 SqlSugar 而非 EF Core
- **原因**：SqlSugar 更轻量、API 更简洁、支持更多数据库方言
- **后果**：团队需要学习 SqlSugar API，不能使用 EF Core 的 Migration 工具
- **关联**：Phase 1 技术选型

## ADR-002: 用户认证采用 JWT + Refresh Token
- **日期**：...

触发时机：

• Phase 1 技术选型时，每项选择自动生成一条 ADR
• Phase 3 系统设计中的关键架构选择
• Phase 9 迭代中遇到需要权衡的技术选择
• 用户主动说"记录这个决策"

tech-debt.md — 技术债追踪

记录已知但暂未处理的技术问题和改进点：

# 技术债 & 已知问题

| ID | 类型 | 描述 | 优先级 | 来源 | 状态 |
|----|------|------|--------|------|------|
| TD-001 | 性能 | 用户列表接口未分页 | P2 | iter-001 | ⏳ 待处理 |
| TD-002 | 安全 | 文件上传未做类型校验 | P1 | iter-003 | 🔄 处理中 |
| TD-003 | 重构 | UserService 过大需拆分 | P3 | iter-005 | ⏳ 待处理 |

触发时机：

• 迭代实现中发现但不阻塞当前功能的问题
• 代码审查中识别的改进点
• 用户主动说"记一个技术债"
• 迭代验证时发现的非阻塞性问题

changelog.md — 变更日志

每次迭代完成后自动追加：

# 变更日志

## [iter-003] 2025-02-15 — 订单管理模块
### 新增
- 订单 CRUD API（FR-010 ~ FR-015）
- 订单列表页面 + 详情页面
### 修改
- 用户模型增加 `lastOrderAt` 字段
### 技术债
- TD-003: UserService 职责过多，需拆分

8.2 跨会话上下文加载

当 Phase 9 迭代开发开始时，自动加载以下文件作为上下文：

必读：
  1. .workcopilot/state.json        → 项目配置 & 历史迭代
  2. .workcopilot/decisions.md      → 技术决策（避免矛盾选择）
  3. .workcopilot/tech-debt.md      → 已知问题（可能关联本次迭代）

按需读取：
  4. .spec-flow/active/*/tasks.md   → 当前任务状态
  5. .spec-flow/active/*/design.md  → 现有架构（增量设计时参考）

记忆协作：团队成员在同一项目工作时，.workcopilot/ 目录提交到 Git，共享技术决策和技术债记录。

---

代码项目 Phase 9: 迭代开发（持续入口）

项目初始化完成后，后续开发通过此阶段循环执行。

触发方式

用户在已初始化的项目中调用 WorkCopilot 时：

• 如果检测到 .workcopilot/state.json 且所有初始化 Phase 已完成
• 自动进入迭代开发模式，使用 vscode_askQuestions：

Q1: 本次迭代要做什么？
  - "🆕 新增功能模块"
  - "🐛 修复 Bug"
  - "♻️ 重构已有模块"
  - "🧪 补充测试"
  - "📦 新增微服务（仅微服务架构）"
  - "� 补充/更新需求 & 设计文档"
  - "📄 生成文档（API文档/PPT/会议纪要）"
  - "🔧 更新工程轨道（Harness）"

补充需求 & 设计文档

当初始化时跳过了 Phase 2-4，或需要更新已有文档时：

1. 检查 .spec-flow/active/{project-name}/ 目录下已有文件
2. 询问用户本次要补充哪些文档：
   - 提案文档（proposal.md）
   - 需求文档（requirements.md）
   - 系统设计（design.md）
   - 任务拆解（tasks.md）
3. 调用 spec-flow-main skill 执行对应阶段的文档生成/更新
   - spec-flow 负责 proposal.md、requirements.md、design.md、tasks.md 的创建和更新
   - WorkCopilot 不自行创建这些文件
4. 更新 state.json 中对应 Phase 的状态

新增功能模块流程

迭代流程图:
  用户描述功能 → brainstorming 探索需求
    → 可选：用户提供参考设计图（同 5.0 参考图导入流程）
    → 调用 spec-flow-main skill 更新 requirements.md（追加 FR/NFR）
    → 调用 spec-flow-main skill 更新 design.md（增量设计）
    → 调用 spec-flow-main skill 更新 tasks.md（追加任务，分配里程碑 & 工时）
    → backend-engineer / frontend-engineer 实现
      （如有参考图，frontend-engineer 参照 analysis.md 生成 UI）
    → test-engineer 编写测试
    → 迭代验证（测试 + lint + 构建检查）
    → 双向同步（tasks.md 状态 + state.json 记录）

任务状态双向同步

核心规则：tasks.md 和 state.json 必须保持一致，任何任务状态变更同时更新两处。

实施期间：

1. 开始执行任务前：将 tasks.md 中该任务状态从 ⏳ 改为 🔄
2. 任务完成后：将 tasks.md 中该任务状态改为 ✅，同时更新 state.json

tasks.md 状态标记：

⏳ 待开始 → 🔄 进行中 → ✅ 完成
                       → ❌ 阻塞（标注阻塞原因）
                       → ⏭️ 跳过（标注跳过原因）

state.json 迭代记录（增强版）：

{
  "iterations": [
    {
      "id": "iter-001",
      "type": "feature",
      "description": "用户管理模块",
      "milestone": "M2",
      "sprint": "Sprint 2",
      "startedAt": "...",
      "completedAt": "...",
      "tasks": [
        { "id": "T-010", "status": "completed", "actualHours": 6 },
        { "id": "T-011", "status": "completed", "actualHours": 10 },
        { "id": "T-012", "status": "completed", "actualHours": 4 }
      ],
      "estimatedHours": 24,
      "actualHours": 20,
      "filesChanged": ["src/Controllers/UserController.cs", "..."],
      "decisions": ["ADR-003"],
      "verification": { "tests": "pass", "lint": "pass", "build": "pass" }
    }
  ]
}

迭代验证闭环

每次迭代的代码实现完成后，必须执行验证步骤：

迭代验证清单:
  1. 运行测试：dotnet test / pytest / vitest
  2. 运行 lint：eslint / dotnet format --verify-no-changes
  3. 构建检查：dotnet build / vite build（确保无编译错误）
  4. 安全检查：对新增代码检查 docs/rules/security.md 中的约束
  5. 更新文档：如有新 API，提醒用户是否需要更新 API 文档

验证结果写入 state.json 的 verification 字段。如有失败项，输出修复建议后等待用户确认。

🔒 会话结束自动持久化（强制规则）

每次会话/迭代完成后，在调用 task_complete 之前，必须自动执行以下持久化操作：

⚠️ 这不是可选步骤。无论会话中做了什么（新功能、修 Bug、重构、补测试、处理技术债），只要产生了代码变更或状态变更，都必须执行。

🔧 PreToolUse Hook 强制保障：项目中的 .github/hooks/update-workcopilot.json 注册了 PreToolUse 拦截脚本，在执行 git commit/push、dotnet build/publish、docker build 前会自动检查 .workcopilot/changelog.md 的最近更新时间（2分钟内）。如果未及时更新，操作将被阻止并注入提示消息，确保持久化契约不可绕过。

必更新文件清单

文件	更新内容	触发条件
.workcopilot/state.json	updatedAt 时间戳、里程碑进度、迭代记录、技术债状态	每次会话必更新
.workcopilot/changelog.md	追加本次变更摘要（新增/修改/删除/技术债）	有代码或配置变更时
.workcopilot/decisions.md	追加架构决策记录（ADR）	做出了技术选型或架构变更时
.workcopilot/tech-debt.md	新增/关闭/更新技术债条目	发现新技术债或解决了已有技术债时
docs/README.md	Docker 版本/Digest/构建命令、技术栈变更、快速开始命令	有 Docker 构建推送、依赖变更、配置变更时
.spec-flow/active/*/tasks.md	任务状态标记（⏳→🔄→✅）	有任务状态变更时

变更检测矩阵

在会话结束前，AI 必须回顾本次会话的所有操作，按以下矩阵自动判定需要更新哪些文件：

会话中做了什么	state.json	changelog.md	README.md	tech-debt.md	decisions.md
任何代码/配置变更	✅ updatedAt	✅ 追加条目	—	—	—
Docker 构建 & 推送	✅ +迭代记录	✅ 部署段	✅ 版本+Digest+构建命令	—	—
新增/修改 API 接口	✅	✅	✅ 如有接口列表段	—	—
修复 Bug	✅	✅ 修复段	—	✅ 如来自已知TD则关闭	—
技术选型/架构变更	✅	✅	✅ 如涉及技术栈段	—	✅ 追加ADR
新增依赖/升级版本	✅	✅	✅ 技术栈表格	—	—
发现但未修的问题	✅	—	—	✅ 新增TD	—
解决已有技术债	✅	✅	—	✅ 状态→✅	—
配置变更(appsettings等)	✅	✅	✅ 如涉及环境配置段	—	—

docs/README.md 自动更新规则

当检测到 Docker 构建/推送操作时，自动更新 docs/README.md 中的以下字段：

# 需要更新的字段（按实际 README 结构定位）：
1. Docker 版本表格中的「最新标签」→ 新版本号
2. Docker 版本表格中的「完整镜像地址」→ 新完整地址
3. Docker 版本表格中的「镜像 Digest」→ 新 Digest（从 docker push 输出中提取）
4. 构建 & 推送命令示例中的版本号 → 新版本号

Digest 提取方式：从 docker push 的终端输出中匹配 sha256: 开头的完整哈希值。

当检测到技术栈变更（新增依赖、升级框架版本等）时，更新 README 中的技术栈表格。

当检测到新增 API 端点时，如 README 中有接口概览段，追加新接口。

时间格式

所有时间戳使用北京时间，格式为 yyyy-MM-dd HH:mm:ss（不带时区后缀）。 state.json 顶层须包含 "timezone": "Asia/Shanghai" 声明。

执行顺序

会话工作完成
  → 0. 回顾本次会话操作清单，对照「变更检测矩阵」判定需更新的文件
  → 1. 更新 state.json（updatedAt + 里程碑进度 + 新迭代记录）
  → 2. 追加 changelog.md（本次变更摘要）
  → 3. 更新 docs/README.md（Docker 版本/Digest、技术栈、接口等）
  → 4. 如有决策：追加 decisions.md
  → 5. 如有技术债变更：更新 tech-debt.md
  → 6. 如有任务状态变更：更新 tasks.md
  → 7. 输出更新摘要（列出实际更新了哪些文件及关键变更）

state.json 更新模板

每次会话至少更新以下字段：

{
  "updatedAt": "2026-05-07 10:30:00",
  "milestones": {
    "M{x}": { "tasksCompleted": "{更新后的数量}" }
  },
  "iterations": [
    {
      "id": "iter-{下一个编号}",
      "date": "2026-05-07 10:30:00",
      "scope": "{本次会话做了什么的一句话摘要}"
    }
  ]
}

changelog.md 追加模板

## [iter-{id}] {yyyy-MM-dd HH:mm:ss} — {范围描述}
### 新增
- {新增的功能/文件}
### 修改
- {修改的内容}
### 修复
- {修复的问题}
### 技术债
- {新增或关闭的技术债}

关键约束：即使用户没有主动要求更新这些文件，AI 也必须在会话结束前自动执行。这是 WorkCopilot 的核心契约——项目记忆永不丢失。

新增微服务（仅 scale = microservice）

1. 询问服务名称和职责描述
2. 在 backend/services/ 下创建新服务目录（复用 5.1 后端脚手架模板）
3. 更新 gateway 路由配置（YARP / Nginx）
4. 更新 docker-compose.yml 添加新服务
5. 生成该服务的独立 CI/CD workflow
6. 更新 shared/Contracts/ 添加新的契约
7. 更新 state.json 的 services 列表

---

⚠️ Harness 意识贯穿全程

每个 Phase 的产出都必须满足 Harness 三层约束：

层	要求	检查点
Context	所有文件结构、命名、分层符合 copilot-instructions.md	Phase 5 脚手架生成后
Constraints	核心目录标注权限、rules 规则已覆盖	Phase 6 harness 生成后
Security	安全基线检查通过、docs/rules/security.md 已生成	Phase 5.9 安全基线后
CI/CD	管线配置正确、所有 job 可解析	Phase 5.7 CI/CD 生成后
GC	无残留临时文件、无冗余代码	Phase 7 验证时

---

交互规则

1. 逐阶段确认：每个 Phase 完成后必须等待用户确认才能继续

2. 中文输出：所有生成的文档使用中文

3. Agent 标注：每个阶段开始时明确标注当前调度的 Agent

4. 进度可视：使用 manage_todo_list 跟踪整体进度

5. 可中断：用户可随时说"跳过"某个 Phase

6. 可回溯：用户可说"回到 Phase X"重新执行某阶段

7. 🔒 自动持久化（最高优先级）：无论会话中做了什么，在会话结束或用户明确表示完成时，必须执行以下步骤：

   1. 回顾本次会话所有操作
   2. 对照「变更检测矩阵」逐行判定哪些文件需要更新
   3. 按「必更新文件清单」逐个更新（state.json → changelog.md → README.md → 其他）
   4. 向用户确认更新结果

   强制触发点：用户说"完成"/"done"/"结束"/"好了"/"推送 Docker 后"等结束性话语时，立即启动持久化流程，不需要用户显式要求。

快速模式

如果用户明确要求跳过逐步确认：

• “快速模式” / “fast mode”
• “一口气执行” / “跳过确认”
• “generate all at once”

则可连续执行所有 Phase，但仍在最后输出完整交付清单供用户确认。

异常恢复

当某个 Phase 执行失败时：

1. 记录失败点：输出失败的 Phase 和具体错误
2. 回滚产物：删除当前 Phase 的不完整产物
3. 提供选项：
   • “重试” — 重新执行失败的 Phase
   • “跳过” — 跳过当前 Phase 继续
   • “中止” — 保留已完成的产物，结束流程