ACP包：核心sdk
用于创建可在MCP服务器、REST API和客户端应用程序之间共享的可重用核心库的模式和模板
安装
快速启动（Bootstrap新项目）
在一个命令中安装ACP和此软件包：
curl -fsSL https://github.com/prmichaelsen/acp-core-sdk/raw/main/agent/scripts/bootstrap.sh | bash这将：
- 安装ACP（如果尚未安装）
- 安装此软件包
- 使用ACP初始化您的项目
仅安装软件包（ACP已安装）
如果您的项目中已经安装了ACP：
@acp.package-install https://github.com/prmichaelsen/acp-core-sdk.git或者使用安装脚本：
./agent/scripts/acp.package-install.sh https://github.com/prmichaelsen/acp-core-sdk.git包含什么
命令
（还没有命令-使用@acp.command-create添加命令）
模式
服务层
- core-sdk.service-base.md -具有生命周期管理、配置和通用功能的基本服务类模式
- core-sdk.service-interface.md -用于依赖注入和松耦合的服务接口模式
- core-sdk.service-container.md -用于依赖注入和生命周期管理的服务容器模式
- core-sdk.服务-错误处理.md -具有自定义错误类和错误代码的一致错误处理模式
- core-sdk.服务加载.md -跨服务格式一致的结构化日志记录模式
适配器层
- core-sdk适配器库.md -基础适配器类模式，为所有部署目标提供生命周期管理
- core-sdk适配器mcp.md -通过模型上下文协议公开服务的MCP适配器模式
- core-sdk.适配器-rest.md -用于通过HTTP REST API公开服务的REST适配器模式
- core-sdk.适配器-cli.md -用于通过命令行界面公开服务的CLI适配器模式
- core-sdk适配器客户端.md -用于将服务公开为可消费库的客户端适配器模式
配置
- core-sdk.config-schema.md -使用Zod的类型安全配置模式，具有验证和组合功能
- core-sdk.config-environment.md -具有类型强制和命名约定的环境变量映射模式
- core-sdk.config-loading.md -具有优先级层次和热重载的分层配置加载模式
- core-sdk.config-secrets.md -带有Secret包装器、vault集成和轮换的秘密管理模式
- core-sdk.config-md -dev/ststage/prod的继承式多环境配置模式
测试
- 核心sdk.测试单元.md -使用Jest、Jest.config.js和托管.spec.ts文件的单元测试模式
- core-sdk测试集成.md -具有.Integration.spec.ts命名约定的集成测试模式
- core-sdk.testing-mocks.md -嘲笑和嘲弄的图案。嘲笑 以及托管的模拟工厂
- 芯sdk.测试夹具.md -测试夹具模式，具有托管的工厂功能。fixtures.ts
- 岩心sdk.测试覆盖率.md -具有jest.config.js阈值和CI强制的覆盖率配置模式
类型系统
- core-sdk.types-shared.md -具有品牌图元、DTO和分页形状的共享域类型模式
- core-sdk.types-config.md -具有Zod派生类型和层范围配置切片的配置类型模式
- core-sdk.types-generic.md -具有DeepPart、Nullable、Maybe和类型助手的泛型实用程序类型模式
- core-sdk.types-error.md -具有区分联合和HTTP/MCP状态映射的错误类型层次结构模式
- core-sdk.types-result.md -用于无异常处理类型化函数错误的结果类型模式
客户端SDK
- core-sdk.client-http-transport.md -基于共享获取的HTTP传输，具有身份验证、错误规范化和SdkResponse输出
- core-sdk客户端响应.md -带throwOnError转义符的Supabase样式{data，error}响应类型
- core-sdk.client-svc.md -具有资源分组类型方法的1:1 REST镜像服务客户端
- core-sdk.client-app.md -面向用例的应用程序客户端，具有web应用程序的复合操作
- core-sdk客户端类型生成.md -使用手写客户端代码生成OpenAPI到TypeScript类型
设计
- core-sdk.体系结构.md -用于创建可在MCP服务器、REST API和客户端应用程序之间共享的可重用核心库的模式和模板
为什么使用此包
- 编写一次，部署到任何地方 -您的业务逻辑作为REST API、MCP服务器、CLI工具或客户端库运行，而无需重写任何内容
- 从第一天开始生产准备就绪 --键入错误，
Result，Zod配置验证和结构化日志从一开始就内置了 - 可通过设计进行测试 —
MockUserRepository、稳定的固定装置，以及ToolCapture使单元和集成测试变得简单 - 复制，不配置 --将源文件直接安装到项目中并对其进行调整；无框架锁定
- 一致的模式 --跨服务、适配器、配置、测试、类型系统和客户端SDK类别的30种模式确保每个项目都遵循相同的约定
用法
安装包并将源文件复制到项目中：
@acp.package-install https://github.com/prmichaelsen/acp-core-sdk.git然后按照 入门指南 或者直接跳到 快速开始 在15分钟内构建一个REST服务器。
部署到多个目标：
Your UserService
├── REST API → examples/rest/
├── MCP server → examples/mcp/
└── CLI tool → examples/cli/看 集成指南 了解分步接线说明。
发展
设置
- 克隆此存储库
- 做出改变
- 跑
@acp.package-validate验证 - 跑
@acp.package-publish发表
添加新内容
- 使用
@acp.pattern-create创建模式 - 使用
@acp.command-create创建命令 - 使用
@acp.design-create创建设计
这些命令会自动执行：
- 为文件名添加命名空间前缀
- 更新package.yaml内容部分
- 更新此README.md
测试
跑 @acp.package-validate 在本地验证您的包。
出版
跑 @acp.package-publish 发布更新。这将：
- 验证包
- 从提交中检测版本冲突
- 更新CHANGELOG.md
- 创建git标签
- 推送到远程
- 试验装置
命名空间约定
此包中的所有文件都使用 core-sdk 命名空间：
- 命令：
core-sdk.command-name.md - 模式：
core-sdk.pattern-name.md - 设计：
core-sdk.design-name.md
依赖项
消费者项目安装这些npm依赖项（确切版本在 config/package.json.template):
| 依赖性 | 目的 |
|---|---|
zod | 运行时配置模式验证 |
express | REST适配器（可选） |
@modelcontextprotocol/sdk | MCP适配器（可选） |
commander | CLI适配器（可选） |
运行时对等依赖关系取决于您使用的适配器。核心类型、错误、配置和服务层在运行时没有依赖关系 zod.
地方发展局
此软件包包括仅用于开发工作流的本地目录：
澄清(agent/clarifications/)
使用此目录记录开发过程中的问题和澄清：
- 使用模板创建澄清文件：
clarification-{N}-{title}.template.md - 记录需求差距、设计问题和实施决策
- 默认情况下为本地：内容文件被忽略，仅
.gitkeep被追踪 - 可选跟踪：从中删除图案
.gitignore跟踪具体澄清
反馈意见(agent/feedback/)
使用此目录在开发过程中获取反馈：
- 记录用户反馈、错误报告和功能请求
- 记录哪些有效，哪些需要改进
- 默认情况下为本地：内容文件被忽略，仅
.gitkeep被追踪 - 可选跟踪：从中删除图案
.gitignore跟踪特定反馈
报告(agent/reports/)
会话报告和开发日志：
- 由自动生成
@acp.report命令 - 默认情况下为本地：内容文件被忽略，仅
.gitkeep被追踪 - 可选跟踪：从中删除图案
.gitignore跟踪特定报告
备注：这些目录遵循相同的模式-它们存在于存储库结构中（通过 .gitkeep)，但默认情况下，它们的内容仅限于本地。您可以选择通过从中删除特定文件来跟踪它们 .gitignore.
贡献
欢迎投稿！拜托：
- 遵循现有的模式结构
- 使用实体创建命令（@acp.pattern-create等）
- 提交前运行@acp.package-validate
- 在CHANGELOG.md中记录您的更改
- 提交前测试安装
许可证
麻省理工学院
作者
帕特里克·迈克尔森