ln-770-crosscutting-setup

路径： 文件路径（references/、../ln-*）均相对于此技能目录。

ln-770-crosscutting-setup

类型： L2 域协调器
类别： 7XX 项目引导
父级： ln-700-project-bootstrap

协调 .NET 和 Python 项目的横切关注点配置。

---

概述

方面	详情
输入	项目根目录
输出	已配置的日志记录、错误处理、CORS、健康检查、API 文档
工作器	ln-771 至 ln-775
技术栈	.NET（ASP.NET Core）、Python（FastAPI）

---

阶段 1：检测项目技术栈

扫描项目文件，确定技术栈。

检测规则：

文件模式	技术栈	框架
*.csproj	.NET	ASP.NET Core
pyproject.toml 或 requirements.txt + FastAPI	Python	FastAPI

操作：

1. 使用 Glob 查找 *.csproj 文件
2. 如果未找到，则使用 Glob 查找 pyproject.toml 或 requirements.txt
3. 如果是 Python 项目，检查依赖项中是否包含 FastAPI
4. 将检测到的技术栈存储到 Context Store

初始 Context Store：

{
  "STACK": ".NET" | "Python",
  "FRAMEWORK": "ASP.NET Core" | "FastAPI",
  "PROJECT_ROOT": "/path/to/project",
  "FRAMEWORK_VERSION": "8.0" | "0.109.0"
}

---

阶段 2：检查现有配置

扫描已配置的横切关注点。

检测模式：

关注点	.NET 模式	Python 模式
日志记录	*.csproj 中的 Serilog、Program.cs 中的 UseSerilog	requirements 中的 structlog、日志配置
错误处理	GlobalExceptionMiddleware、UseExceptionHandler	@app.exception_handler、exception_handlers.py
CORS	AddCors、UseCors	CORSMiddleware
健康检查	AddHealthChecks、MapHealthChecks	/health 路由
API 文档	AddSwaggerGen、UseSwagger	FastAPI 自动生成

操作：

1. 使用 Grep 搜索每种模式
2. 将已配置的关注点标记为 skip: true
3. 使用检查结果更新 Context Store

更新后的 Context Store：

{
  "concerns": {
    "logging": { "configured": false },
    "errorHandling": { "configured": false },
    "cors": { "configured": true, "skip": true },
    "healthChecks": { "configured": false },
    "apiDocs": { "configured": false }
  }
}

---

阶段 3：调用工作器（有条件）

仅对尚未配置的关注点委派给工作器。

工作器调用顺序：

顺序	工作器	条件	技能调用
1	ln-771-logging-configurator	logging.configured == false	/skill ln-771-logging-configurator
2	ln-772-error-handler-setup	errorHandling.configured == false	/skill ln-772-error-handler-setup
3	ln-773-cors-configurator	cors.configured == false	/skill ln-773-cors-configurator
4	ln-774-healthcheck-setup	healthChecks.configured == false	/skill ln-774-healthcheck-setup
5	ln-775-api-docs-generator	apiDocs.configured == false	/skill ln-775-api-docs-generator

调用（有条件——如果关注点已配置，则跳过）：

Skill(skill: "ln-771-logging-configurator", args: "{STACK} {FRAMEWORK}")
Skill(skill: "ln-772-error-handler-setup", args: "{STACK} {FRAMEWORK}")
Skill(skill: "ln-773-cors-configurator", args: "{STACK} {FRAMEWORK}")
Skill(skill: "ln-774-healthcheck-setup", args: "{STACK} {FRAMEWORK}")
Skill(skill: "ln-775-api-docs-generator", args: "{STACK} {FRAMEWORK}")

将 Context Store 传递给每个工作器。

工作器响应格式：

{
  "status": "success" | "skipped" | "error",
  "files_created": ["path/to/file.cs"],
  "packages_added": ["Serilog.AspNetCore"],
  "message": "Configured structured logging with Serilog"
}

---

阶段 4：生成聚合文件

为所有横切服务创建单一入口点。

.NET：Extensions/ServiceExtensions.cs

根据已配置的工作器生成：

// Structure only - actual code generated via MCP ref
public static class ServiceExtensions
{
    public static IServiceCollection AddCrosscuttingServices(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        // Calls added based on configured workers:
        // services.AddLogging(configuration);      // if ln-771 ran
        // services.AddCorsPolicy(configuration);   // if ln-773 ran
        // services.AddHealthChecks();              // if ln-774 ran
        // services.AddSwaggerServices();           // if ln-775 ran
        return services;
    }
}

Python：middleware/init.py

根据已配置的工作器生成：

# Structure only - actual code generated via MCP ref
def configure_middleware(app):
    # Middleware added based on configured workers:
    # configure_logging(app)        # if ln-771 ran
    # configure_error_handlers(app) # if ln-772 ran
    # configure_cors(app)           # if ln-773 ran
    # configure_health_routes(app)  # if ln-774 ran
    pass

---

阶段 5：摘要报告

显示所有已配置关注点的摘要。

输出格式：

Cross-cutting Setup Complete
============================
Stack: .NET (ASP.NET Core 8.0)

Configured:
  ✓ Logging (Serilog) - Extensions/LoggingExtensions.cs
  ✓ Error Handling - Middleware/GlobalExceptionMiddleware.cs
  ✓ CORS - Extensions/CorsExtensions.cs
  ✓ Health Checks - Extensions/HealthCheckExtensions.cs
  ✓ API Docs (Swagger) - Extensions/SwaggerExtensions.cs

Skipped (already configured):
  - None

Entry Point: Extensions/ServiceExtensions.cs
  Add to Program.cs: builder.Services.AddCrosscuttingServices(builder.Configuration);

Packages to Install:
  dotnet add package Serilog.AspNetCore
  dotnet add package Swashbuckle.AspNetCore

---

工作器

工作器	用途	技术栈
ln-771-logging-configurator	结构化日志记录	.NET（Serilog）、Python（structlog）
ln-772-error-handler-setup	全局异常中间件	.NET、Python
ln-773-cors-configurator	CORS 策略配置	.NET、Python
ln-774-healthcheck-setup	/health 端点	.NET、Python
ln-775-api-docs-generator	Swagger/OpenAPI	.NET（Swashbuckle）、Python（FastAPI 内置）

---

Context Store 接口

Worker 通过 Context Store 接收和返回：

提供给 Worker 的输入：

{
  "STACK": ".NET",
  "FRAMEWORK": "ASP.NET Core",
  "FRAMEWORK_VERSION": "8.0",
  "PROJECT_ROOT": "/path/to/project",
  "ENVIRONMENT": "Development"
}

Worker 的输出：

{
  "status": "success",
  "files_created": [],
  "packages_added": [],
  "registration_code": "services.AddLogging(configuration);"
}

---

幂等性

此技能具有幂等性：

• 第 2 阶段检测现有配置
• 如果已配置，Worker 会跳过
• 聚合文件会保留现有条目

---

关键规则

• 跳过已配置的关注项 — 第 2 阶段的检测必须控制 Worker 调用（设置 skip: true）
• 向每个 Worker 传递 Context Store — Worker 依赖 STACK、FRAMEWORK、PROJECT_ROOT
• 仅为实际运行的 Worker 生成聚合文件 — 不要为已跳过的关注项添加注册调用
• 仅支持 .NET 和 Python — 通过 *.csproj 或 pyproject.toml/requirements.txt + FastAPI 检测
• 幂等执行 — 重新运行不得重复配置或破坏现有设置

TodoWrite 格式（必需）：

- Detect project stack (in_progress)
- Check existing configuration (pending)
- Invoke ln-771-logging-configurator (pending)
- Invoke ln-772-error-handler-setup (pending)
- Invoke ln-773-cors-configurator (pending)
- Invoke ln-774-healthcheck-setup (pending)
- Invoke ln-775-api-docs-generator (pending)
- Generate aggregation file (pending)
- Summary report (pending)

Worker 调用（必需）

宿主技能调用： 必须使用 Skill(skill: "...", args: "...") 进行委派。

• Claude：严格按所示方式调用 Skill 工具。
• Codex：如果没有 Skill 工具，则在可用技能中找到指定技能，读取其 SKILL.md，将 args 视为 $ARGUMENTS，执行该技能工作流，然后携带其结果/产物返回此处。
• 不要内联 Worker 逻辑，也不要在未执行目标技能的情况下将 Worker 标记为完成。

阶段	Worker	上下文
3	ln-771-logging-configurator	共享（Skill 工具）— 结构化日志设置
3	ln-772-error-handler-setup	共享（Skill 工具）— 全局异常中间件
3	ln-773-cors-configurator	共享（Skill 工具）— CORS 策略配置
3	ln-774-healthcheck-setup	共享（Skill 工具）— /health 端点
3	ln-775-api-docs-generator	共享（Skill 工具）— Swagger/OpenAPI 文档

所有 Worker： 通过 Skill 工具调用 — Worker 可看到协调器上下文。

完成定义

• 检测并将项目技术栈存入 Context Store
• 检测现有配置（第 2 阶段完成）
• 将所有未配置的关注项委派给 Worker（ln-771 到 ln-775）
• 生成聚合入口点（ServiceExtensions.cs 或 middleware/__init__.py）
• 显示摘要报告，列出已配置/已跳过的关注项和软件包安装命令

参考文件

• Worker 技能：ln-771-logging-configurator/SKILL.md 到 ln-775-api-docs-generator/SKILL.md
• references/logging_patterns.md — 各技术栈的结构化日志模式（传递给 ln-771）
• references/error_handling_patterns.md — 全局异常处理模式（传递给 ln-772）
• references/cors_configuration.md — 各技术栈的 CORS 开发/生产策略（传递给 ln-773）

---

第 6 阶段：元分析

可选参考：仅当用户要求进行运行后元分析或按协议格式进行运行反思时，才加载 references/meta_analysis_protocol.md。

技能类型：execution-orchestrator。收到请求时，在所有阶段完成后运行。使用 execution-orchestrator 格式输出到聊天中。

---

版本： 2.0.0 最后更新： 2026-01-10