DOA Harness — 一键搭建 Copilot 工程轨道（团队版）

核心理念

Copilot 的上限不取决于提示词，而取决于它运行在怎样的工程轨道上。 三层公式：Context（给什么）→ Constraints（守什么）→ GC（清什么）。

运行模式

工作流

调用 skill
  → Step 0: 判断运行模式（初始化 / 增量更新 / 预览）
  → Step 1: 深度探测项目结构与技术栈
  → Step 2: 交互确认关键信息
  → Step 3: 生成 / 更新 5 类配置文件
  → Step 4: 注入 GC 指令
  → Step 5: 验证完整性 & 一致性
  → Step 6: 输出 Day-1 验证指令

Step 0: 判断运行模式

1. 检查参数中是否含 --update 或 --dry-run
2. 扫描工作区，检查 .github/copilot-instructions.md 是否已存在

• 已存在且未指定 --update：提示用户 "Harness 已初始化，是否切换到增量更新模式？"
• 不存在：进入初始化模式

Step 1: 深度探测项目结构与技术栈

1.1 递归扫描子项目

不再只看根目录。用 list_dir 递归扫描根目录及一级子目录，收集所有包含信号文件的子项目：

扫描策略：
1. list_dir 根目录 → 识别子目录
2. 对每个子目录 list_dir → 查找信号文件
3. 构建子项目列表: [{name, path, stack, signals}]

1.2 信号文件匹配表

1.3 前端框架深度探测

当检测到 package.json 时，必须读取其 dependencies / devDependencies 来判断：

同时检测：

• 包管理器: 检查 yarn.lock → Yarn | pnpm-lock.yaml → pnpm | package-lock.json → npm
• CSS 方案: 检查 tailwind.config.* → Tailwind | .less 文件 → Less | *.module.css → CSS Modules
• 状态管理: 检查依赖中的 zustand / dva / redux / pinia / vuex / ahooks
• 请求层: 检查 axios / umi-request / @tanstack/react-query / swr
• 测试框架: 检查 vitest / jest / @testing-library/* / cypress
• Lint 工具: 检查 eslint / prettier / biome

1.4 后端框架深度探测

.NET 项目（检测到 .csproj / .sln）：

• 读取 .csproj 的 <TargetFramework> → 判断 .NET 版本
• 读取 <Sdk> 属性 → Microsoft.NET.Sdk.Web 为 Web 项目，Microsoft.NET.Sdk.Worker 为后台服务
• 扫描 Program.cs / Startup.cs → 判断 Minimal API / MVC / 传统分层
• 扫描 NuGet 依赖 → EF Core / Dapper / MediatR / FluentValidation 等
• 检查认证方式 → Azure AD / JWT / IdentityServer

Python 项目：

• 读取 pyproject.toml 或 requirements.txt → FastAPI / Django / Flask
• 检测 ORM → SQLAlchemy / Django ORM / Tortoise

1.5 CI/CD 探测

扫描以下文件以识别 CI 平台：

1.6 代码托管平台探测

通过 .git/config 或目录特征推断：

1.7 探测结果数据结构

将所有探测结果汇总为结构化数据，供后续步骤使用：

project:
  name: "{项目名}"
  type: "monorepo" | "single"
  hosting: "github" | "gitlab" | "azure-devops"
  ci: "github-actions" | "azure-pipelines" | "gitlab-ci"
  subprojects:
    - name: "{子项目名}"
      path: "{相对路径}"
      stack: "react-ts" | "vue-ts" | "dotnet" | "python" | ...
      framework: "{具体框架}"
      package_manager: "yarn" | "pnpm" | "npm" | null
      css: "less" | "tailwind" | "css-modules" | null
      state: "dva" | "zustand" | "pinia" | null
      request: "umi-request" | "axios" | "react-query" | null
      test: "vitest" | "jest" | "xunit" | "pytest" | null
      lint: "eslint" | "prettier" | "biome" | "dotnet-format" | null
      entry: "{入口文件路径}"
      verify_chain: ["{cmd1}", "{cmd2}", "{cmd3}"]

Step 2: 交互确认

使用 vscode_askQuestions 向用户确认以下关键信息（一次性收集）：

必填项

1. 项目描述: 一句话概括项目（用于 copilot-instructions.md 项目概述）
2. 确认探测结果: 展示探测到的子项目列表和技术栈，让用户确认或修正
3. 代码托管平台: GitHub / GitLab / Azure DevOps（影响 CODEOWNERS 路径和语法）

可选项（有默认值）

1. 团队 Owner 列表: 输入格式 @user1 @user2，默认 @todo-fill-team
2. 额外编码规则: 是否有团队特有的编码规约需要生成为 rules/ 文件
3. 是否将 `.vscode/tasks.json` 纳入版本控制: 默认 Yes

增量更新模式下：跳过已确认的信息，仅询问新增部分（如新发现的子项目）

Step 3: 生成配置文件

按以下顺序依次生成 5 类文件。

初始化模式：生成前检查是否已存在，已存在则跳过并提示。 增量更新模式：读取已有文件，仅 patch 新增内容（如新模块加入模块地图），不覆盖用户自定义段落。 预览模式：渲染模板内容输出到聊天窗口，不写入文件。

每个生成的文件头部加注版本标记：

# Generated by doa-harness v2.0 on {YYYY-MM-DD}

3.1 copilot-instructions.md

路径：.github/copilot-instructions.md

读取 templates/copilot-instructions.md 获取骨架模板。

模板采用骨架 + 占位符模式，不硬编码任何特定框架：

段落结构（固定）：
1. 项目概述 — {project.name} + 各子项目入口
2. 技术栈 — 按子项目分段，每段由探测结果填充
3. 安全边界 — 按子项目分段
4. 前后端联动（仅 monorepo）
5. 验证命令 — 从 verify_chain 生成
6. 代码约定 — 按语言生成
7. 操作安全 — 合并 CI 平台 + 核心目录
8. 垃圾回收（固定段落）

占位符清单：

• {project_description} — 用户输入的项目描述
• {sub.name} / {sub.entry} — 子项目名和入口
• {sub.framework} — 具体框架（UmiJS / Next.js / ASP.NET Core...）
• {sub.state} — 状态管理方案
• {sub.css} — CSS 方案
• {sub.request} — 请求层方案
• {sub.package_manager} — 包管理器
• {ci_platform} — CI 平台名及配置文件路径
• {hosting_platform} — 代码托管平台

3.2 AGENTS.md

路径：.github/AGENTS.md

读取 templates/agents-md.md 获取骨架模板。

生成规则：

• 快速入口: 自动探测 docs/、README.md、CHANGELOG.md 等是否存在并列出
• 关键约束: 自动扫描 rules/ 目录列出
• 模块地图: 对每个子项目，扫描其目录结构并按下表标注

权限标注规则（按目录名模式匹配）：

生成后通过交互让用户确认或修正权限标注，避免误判。 总行数控制在 200 行以内。

3.3 tasks.json

路径：.vscode/tasks.json

读取 templates/tasks-json.md 获取骨架模板。

支持 N 个子项目，生成逻辑：

对每个子项目 sub:
  1. 根据 sub.verify_chain 生成对应 task 列表
  2. 每个 task 的 label 格式: "{sub.name}:{step}"
  3. 每个 task 添加 options.cwd = "${workspaceFolder}/{sub.path}"
  4. 生成子验证任务: "verify:{sub.name}" dependsOn 该子项目所有 step
最后生成总验证任务:
  "verify" dependsOn 所有 "verify:{sub.name}"

包管理器感知：

• 检测到 yarn.lock → 命令用 yarn
• 检测到 pnpm-lock.yaml → 命令用 pnpm
• 默认 → 命令用 npm run

problemMatcher 映射：

• TypeScript 编译 → ["$tsc"]
• ESLint → ["$eslint-stylish"]
• .NET build → ["$msCompile"]
• 其他 → []

3.4 CODEOWNERS

路径：根据代码托管平台决定

读取 templates/codeowners.md 获取骨架模板。

生成规则：

• 扫描项目所有子项目的核心目录，自动标注 owner
• 使用用户在 Step 2 提供的团队 Owner 列表（未提供则用 @todo-fill-team）
• CI/CD 配置文件自动纳入 CODEOWNERS
• Agent 配置文件（copilot-instructions.md、AGENTS.md）纳入 CODEOWNERS
• GitLab 项目使用 [Section] 分组语法增强可读性

3.5 rules/*.md

路径：rules/ 目录

读取 templates/rules.md 获取各技术栈的规则模板。

每条规则文件包含：

• 规则名称 + 原因
• 正确示例 ✅
• 错误示例 ❌
• 检测方式

根据技术栈生成核心规则 + 通用规则：

按技术栈生成：

通用规则（所有项目都生成）：

用户自定义规则： 如果用户在 Step 2 提供了额外规约，为每条生成一个独立 rules/{name}.md 文件。

Step 4: 注入 GC 指令

在 copilot-instructions.md 的末尾追加 GC 段落：

# 垃圾回收

每次完成任务后，检查是否有：
- 临时文件、未使用的 import / using
- 重复代码或重复函数
- 过期的 TODO / FIXME 注释
如有，顺手清理。

Step 5: 验证完整性 & 一致性

生成完成后执行以下检查：

5.1 文件存在性

确认 5 类文件全部存在（Azure DevOps 项目跳过 CODEOWNERS）。

5.2 内容一致性校验

5.3 生成 harness 自检 task

在 tasks.json 中追加一个 verify:harness 任务，检查 5 类文件的存在性：

{
  "label": "verify:harness",
  "type": "shell",
  "command": "echo Checking harness files... && test -f .github/copilot-instructions.md && test -f .github/AGENTS.md && test -f .vscode/tasks.json && test -f CODEOWNERS && test -d rules/ && echo 'All harness files OK' || echo 'MISSING harness files!'",
  "problemMatcher": []
}

Step 6: 输出 Day-1 验证指令

输出生成文件清单，并给出 Day-1 验证指令：

打开 Copilot Agent 模式，输入：
"读一下项目指令，然后告诉我：
 1. 哪些目录不能修改？
 2. 验证命令是什么？
 3. 哪些操作需要先确认？"

如果 Copilot 能准确回答这 3 个问题，说明 Harness 已生效。

增量更新行为说明

当以 --update 模式运行时：

1. copilot-instructions.md: 读取已有文件，仅更新探测到变化的段落（如新子项目的技术栈段），保留用户手动添加的自定义段落
2. AGENTS.md: 重新扫描目录结构，将新目录追加到模块地图末尾，保留已有目录的标注和用户修正
3. tasks.json: 检测新子项目，追加对应的 task，更新 verify 的 dependsOn 列表
4. CODEOWNERS: 追加新目录的 owner 映射，不修改已有行
5. *rules/.md**: 仅生成不存在的规则文件，已有文件不动

快速参考