Puppet.Core 1.1.1

Puppet.Core

中文 · English

中文

简介

Puppet.Core 是一个由 AI Agent 自己开发出来的且为 AI Agent 使用而设计的 .NET 操控框架：为任意 .NET 类型（含 WinForms 窗体与控件）自动暴露可操控的 WebApi 接口，通过反射生成能力描述，支持运行时状态查询、属性读写与方法调用。

它不是给开发者用的库，而是 Agent 的工具——Agent 借助它模拟真实用户操作、观测运行时状态，对宿主程序实施自动化调试与测试。

两种集成方式

设计理念

Puppet.Core 让 Agent 自动调试应用程序——面向需要编译后进行调试的应用程序类型。它不限于 C#，移植到其他语言同样适用。最关键的核心在于 DEVELOPMENT.md：这个文件相当于一份 Skill 说明，让 Agent 在整个应用开发周期内都具备自动调试能力，并且具备自我改进/演化的能力（尤其是源码导入模式下）。

子项目

TestGround：自我调试与演进试验场

四个 TestGround 应用是框架的"练兵场"：它们各自实现一个有实际意义的小型真实应用（任务看板、支出账本、阅读清单、库存预留），覆盖 WinForms、Console、WPF、ASP.NET Core 四类典型宿主形态。Agent 在其上持续工作——用 Puppet 端点模拟真实用户操作、观测状态、发现问题——即可逐步覆盖对应类型程序设计的方方面面，并把经验沉淀在各项目自己的 AGENTS.md / README.md / DEVELOPMENT.md 中，反过来驱动框架修复与演进。原则：业务代码保持优雅、清晰、简洁、面向人类审美的美观易用；框架改动必须由可复现的问题证据驱动，不投机性加功能。

快速开始（供 Agent 阅读）

安装 Puppet.Core 只需 Agent 阅读本 README 即可。
Agent 在安装时应询问用户采用哪种部署模式：

• 源码引用 —— 将 Puppet.Core 源码放入宿主工程（本仓库 Puppet.Core/ 目录），Agent 可修改框架源码并重新编译
• NuGet 包 —— 从 NuGet.org 安装 Puppet.Core，使用发布版本的静态架构经验

Puppet.Core 包可从 NuGet.org 获取：

dotnet add package Puppet.Core --source https://api.nuget.org/v3/index.json

安装后请先阅读下方“文档”中的指南，并将读取入口写入宿主工程的 AGENTS.md。

目标框架：net8.0 / net9.0 / net10.0。宿主程序实现 IPuppet（3 个属性），即可被 Agent 发现与操控。

内建服务器（宿主无 Web 服务器）：

PuppetKeyVault.SetKey("your-secret");
new PuppetWebServer().Start("0.0.0.0:9090");

WinForms 宿主（启用控件端点）：

new PuppetWebServer().UseFormControls().Start("0.0.0.0:9090");

注入已有服务器（宿主已有 WebServerBase 子类）：实现 IPuppet，构造时 this.Register()，并在 ProcessWebRequest 中调用 PuppetWebHandler.TryHandle(ref req)。

端点一览

所有请求携带 Authorization: Bearer <key>：

文档

• DEVELOPMENT.md —— 面向 AI Agent 的开发与使用指南：集成模式、调用约定、安全约束、实战踩坑记录。

Agent 读取入口（二选一）：

1. /agent/docs 端点：宿主运行后，Agent 使用 Authorization: Bearer <全局密钥> 请求 GET /agent/docs，即可取回与运行中程序集版本一致的 DEVELOPMENT.md（text/markdown; charset=utf-8），无需实例名。建议 Agent 在安装/集成时将以下指南写入宿主工程的 AGENTS.md，供后续会话发现入口；NuGet 不会自动修改该文件：

   使用 PuppetCore 调试宿主前，先读取宿主 Puppet 服务的 GET /agent/docs，通过 Authorization Bearer 头传递运行时全局密钥；宿主未启动或所用旧版本不支持此端点时，读取已还原 NuGet 包中的 DEVELOPMENT.md。记录服务地址及密钥获取方式，不要将实际密钥写入文件或日志。

2. NuGet 包内文档：还原依赖后，可读取 <global-packages>/puppet.core/<version>/DEVELOPMENT.md。Windows 默认路径为 %USERPROFILE%\.nuget\packages\puppet.core\<version>\DEVELOPMENT.md，Linux/macOS 为 ~/.nuget/packages/puppet.core/<version>/DEVELOPMENT.md。在宿主目录运行 dotnet nuget locals global-packages --list 查询缓存位置；如工程自定义了还原目录，以 obj/project.assets.json 中的 packageFolders 为准，<version> 使用该文件中实际解析的 Puppet.Core 版本，而非任取缓存中的最新版本。

许可证

MIT · Copyright (c) 2026 Xiaoyuvax

English

Overview

Puppet.Core is a .NET framework built for AI agents: it automatically exposes controllable WebApi endpoints for any .NET type (including WinForms windows and controls), generates capability descriptions via reflection, and supports runtime state queries, property read/write, and method invocation.

It is not a library for human developers — it is a tool for agents. Agents use it to simulate real user interactions and observe runtime state, driving automated debugging and testing of host applications.

Integration Modes

Philosophy

Puppet.Core enables agents to automatically debug applications — specifically applications that require compilation before debugging. It is not limited to C#; porting to other languages works the same way. The most critical piece is DEVELOPMENT.md: this file serves as a Skill specification, giving agents automatic debugging capability throughout the entire application development lifecycle, with the ability to self-improve and evolve (especially in source-import mode).

Sub-projects

TestGround: self-debugging and evolution labs

The four TestGround apps are the framework's training grounds. Each implements a small but genuinely useful application (task board, expense ledger, reading list, inventory reservations) covering four typical host shapes: WinForms, Console, WPF, and ASP.NET Core. By continuously working on them — simulating real user actions through Puppet endpoints, observing state, and surfacing issues — agents progressively cover the design landscape of each app type and distill experience into each project's own AGENTS.md / README.md / DEVELOPMENT.md, which in turn drives framework fixes and evolution. Principles: app code stays elegant, clear, concise, and pleasant for humans; framework changes must be driven by reproducible evidence, never speculative features.

Quick Start (for Agent)

Installing Puppet.Core only requires the Agent to read this README.
The Agent should ask the user which deployment mode to use during installation:

• Source reference — add Puppet.Core source into the host project (this repo's Puppet.Core/ directory); Agent can modify framework source and recompile
• NuGet package — install Puppet.Core from NuGet.org; use the released version's static architectural experience

The Puppet.Core package is available on NuGet.org:

dotnet add package Puppet.Core --source https://api.nuget.org/v3/index.json

After installation, read the guide under "Documentation" below and add the read entry to the host project's AGENTS.md.

Target framework: net8.0 / net9.0 / net10.0. A host implements IPuppet (3 properties) to become discoverable and controllable by agents.

Built-in server (host has no web server):

PuppetKeyVault.SetKey("your-secret");
new PuppetWebServer().Start("0.0.0.0:9090");

WinForms host (enables the control endpoint):

new PuppetWebServer().UseFormControls().Start("0.0.0.0:9090");

Inject into an existing server (host already subclasses WebServerBase): implement IPuppet, call this.Register() in the constructor, and invoke PuppetWebHandler.TryHandle(ref req) inside ProcessWebRequest.

Endpoints

All requests require the Authorization: Bearer <key> header:

Documentation

• DEVELOPMENT.md — the AI-agent-oriented development and usage guide: integration modes, calling conventions, security rules, and pitfalls from practice.

Agent read entries (choose one):

1. /agent/docs endpoint: while the host is running, request GET /agent/docs with Authorization: Bearer <global key> to retrieve DEVELOPMENT.md matching the running assembly (text/markdown; charset=utf-8). No instance name is required. Agents should add the following guidance to the host project's AGENTS.md during installation/integration so future sessions can discover it; NuGet does not modify that file automatically:

   Before debugging the host with PuppetCore, read GET /agent/docs from the host's Puppet service, passing the runtime global key in the Authorization Bearer header. If the host is not running or an older version lacks this endpoint, read DEVELOPMENT.md from the restored NuGet package. Record the service address and how to obtain the key, never the actual key in files or logs.

2. Documentation inside the NuGet package: after restore, read <global-packages>/puppet.core/<version>/DEVELOPMENT.md. Defaults are %USERPROFILE%\.nuget\packages\puppet.core\<version>\DEVELOPMENT.md on Windows and ~/.nuget/packages/puppet.core/<version>/DEVELOPMENT.md on Linux/macOS. Run dotnet nuget locals global-packages --list from the host directory to locate the cache. For project-specific restore directories, use packageFolders in obj/project.assets.json; choose the Puppet.Core version actually resolved in that file, not simply the newest cached version.

License

MIT · Copyright (c) 2026 Xiaoyuvax