chore: 简化 MAF1.Core 编译配置并加入 AGENTS.md

- MAF1.Core 移除 <EnableDefaultCompileItems>false> 与显式 Compile Include，改由 SDK 默认编译所有 .cs，新增文件无需再手动登记 csproj - 新增 AGENTS.md，沉淀项目结构、构建命令、关键陷阱与约定 - .gitignore 移除 /AGENTS.md 与 /CLAUDE.md 排除项，允许指令文件入库
2026-09-02 11:21:03 +08:00
parent b0e89b6092
commit d1b979f2db
3 changed files with 46 additions and 23 deletions
@@ -364,6 +364,4 @@ FodyWeavers.xsd
 /ZETMP.rar
 .gitnexus
 /.claude/skills/gitnexus
-/AGENTS.md
-/CLAUDE.md
 .vscode
@@ -0,0 +1,46 @@
+# MAF1 — Agent Instructions
+
+.NET 10 多智能体工作流编排演示仓库（Microsoft Agents AI + ASP.NET Core + 进程外插件）。完整文档见 [README.md](README.md) 和 [plugins/README.md](Plugins/README.md)。
+
+## 项目结构（6 个工程，`MAF1.slnx`）
+
+| 工程 | 作用 |
+|------|------|
+| `MAF1.Core` | 唯一共享层：Agent、Tool、LLM 工厂、插件协议。所有工程都引用它 |
+| `MAF1` | 命令行工作流（`node`/`edge` 两种条件写法） |
+| `MAF1.Route` | 命令行路由（方案 C，`WithHandoff` 交接） |
+| `MAF1.Web` | ASP.NET Core Minimal API 可视化编排器 + `wwwroot`（原生 JS，无 npm） |
+| `Plugins/file-city`、`Plugins/weather` | 进程外插件（stdin/stdout JSON） |
+
+## 构建 / 运行
+
+```powershell
+dotnet build                                    # 还原 + 编译（在仓库根目录）
+dotnet run --project MAF1 -- node Data/cities.txt
+dotnet run --project MAF1 -- edge Data/not-cities.txt
+dotnet run --project MAF1.Route -- Graphs/city-weather.json
+dotnet run --project MAF1.Web                   # 浏览器 http://127.0.0.1:5288
+```
+
+没有测试工程。验证靠 UI 示例图 + 两个 CLI 命令。解决方案是 `MAF1.slnx`（**不是 `.sln`**）。
+
+## 关键陷阱（改代码前必读）
+
+1. **插件运行时读的是 bin 输出，不是源码树**：`PluginScanner` 扫描 `MAF1.Web.exe` 旁的 `plugins/`。改完 `Plugins/` 源码必须重新 `dotnet build`（靠 `MAF1.Web.csproj` 的 `PublishPluginFolders` 目标复制）或点前端「刷新节点」。
+2. **不要提交 API Key**：Key 走环境变量或 `appsettings.json` 的 `Llm` 段（环境变量优先）。注意 `**/Properties/launchSettings.json` 里目前硬编码了一个真实 Key，新增/修改配置时切勿再写入真实密钥，也勿把含 Key 的版本提交。
+3. **插件 stdout 只能输出一行 JSON**：日志和提示走 stderr，否则宿主 `ParseOutputs` 会解析失败。
+4. **天气查询必须用 `WeatherTools.CreateHttpClient()`**：带 20s 超时和正确 User-Agent，直接 `new HttpClient()` 可能被 wttr.in 拒绝。
+5. **LLM 输出解析前先过 `JsonText.UnwrapObject`**：剥离模型回复的 ```json ``` 围栏后再反序列化。
+
+## 约定
+
+- **JSON 序列化**：camelCase + 反射（无 source gen）。统一入口 `MAF1.PluginContract.PluginJson.Options`；Web 用 `ConfigureHttpJsonOptions`。个别类用 `[JsonPropertyName(...)]` 显式标注。
+- **LLM 创建只经 `AgentFactory.Load` / `AgentFactory.CreateAgent`**（`MAF1.Core/Utils/AgentFactory.cs`）。识别环境变量 `OPENAI_API_KEY` / `OPENAI_ENDPOINT`（或 `OPENAI_BASE_URL`）/ `OPENAI_CHAT_MODEL`；DeepSeek endpoint 会自动禁用 thinking（`DeepSeekThinking.Disable`）。
+- **每个 `Program.cs` 第一行调用 `WindowsConsole.EnableUtf8()`**（避免中文乱码）。
+- **Agent 用静态工厂**：`FileCityAgent.Create` / `WeatherAgent.Create`，业务逻辑集中在 `RunAsync`。CLI、Web 系统节点、插件三处复用同一套。
+- **文件组织**：多数一文件一类；但 `PluginManifest.cs`、`DecisionModels.cs`、`RouteGraph.cs` 等有意把多个紧相关小类放一个文件，属惯例。
+- **命名空间与目录不严格对应**：如 `MAF1.Web/PluginHost/*.cs` 用 `MAF1.Plugins`；Core 里 `Agents/FileCity` 用 `MAF1.Agents.FileCity`，而 `AgentStepResult.cs` 用 `MAF1.Core.Agents`。
+
+## 建议的上手路径
+
+`README.md` → `MAF1.Core/Utils/AgentFactory.cs`（LLM 配置）→ `FileCityAgent.cs` / `WeatherAgent.cs`（Agent 写法）→ `PluginContract/PluginStdio.cs` + `MAF1.Web/PluginHost/PluginProcessRunner.cs`（插件协议两端）→ `MAF1/Workflows/CityWeatherWorkflow.cs`（Workflow 用法）→ `MAF1.Route/HandoffGraphBuilder.cs`（Handoff 用法）。
@@ -5,29 +5,8 @@
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <RootNamespace>MAF1.Core</RootNamespace>
-    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
  </PropertyGroup>

-  <ItemGroup>
-    <Compile Include="Agents\AgentStepResult.cs" />
-    <Compile Include="Agents\SystemNodeTypes.cs" />
-    <Compile Include="Agents\FileCity\CityExtraction.cs" />
-    <Compile Include="Agents\FileCity\FileCityAgent.cs" />
-    <Compile Include="Agents\Weather\WeatherAgent.cs" />
-    <Compile Include="Decisions\ConsoleDecisionPrompt.cs" />
-    <Compile Include="Decisions\DecisionModels.cs" />
-    <Compile Include="PluginContract\PluginManifest.cs" />
-    <Compile Include="PluginContract\PluginStdio.cs" />
-    <Compile Include="Tools\FileTools.cs" />
-    <Compile Include="Tools\WeatherOptions.cs" />
-    <Compile Include="Tools\WeatherTools.cs" />
-    <Compile Include="Utils\AgentFactory.cs" />
-    <Compile Include="Utils\DeepSeekThinking.cs" />
-    <Compile Include="Utils\JsonText.cs" />
-    <Compile Include="Utils\LlmOptions.cs" />
-    <Compile Include="Utils\WindowsConsole.cs" />
-  </ItemGroup>
-
  <ItemGroup>
    <PackageReference Include="Azure.AI.OpenAI" Version="2.1.0" />
    <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.19.0" />