{"_id":"@aweeclaw/harness-core","_rev":"2-a0b2adf692c8740f9ab676d375a21d0c","name":"@aweeclaw/harness-core","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@aweeclaw/harness-core","version":"1.0.0","keywords":["ai-agent","harness","pipeline","middleware","capability","observability","lifecycle","di-container"],"author":{"name":"awee","email":"awee.worker@gmail.com"},"license":"MIT","_id":"@aweeclaw/harness-core@1.0.0","maintainers":[{"name":"awee","email":"402661910@qq.com"}],"homepage":"https://github.com/jweelee/aweeclaw","bugs":{"url":"https://github.com/jweelee/aweeclaw/issues"},"dist":{"shasum":"a5b966518997b365d02cbb8cd0c9f75ca68281cf","tarball":"https://registry.npmjs.org/@aweeclaw/harness-core/-/harness-core-1.0.0.tgz","fileCount":115,"integrity":"sha512-hL1nFJ4eP7PG5lBQ32OvtG0AFG2Rry6W9Yxq6WDrAKirPVUHwBwlSoVQrsCLAQkEFGz/wVx19LrdpYXHSJxL5w==","signatures":[{"sig":"MEQCIEnY5OgMJAKpuCi4A00raczQoq7RLCBrQ8lYvDhFf6kvAiAxnftxTAJMJdFEGvwfvXXh4kKW/NWoRhxuXIuXjFiw5w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":159258},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"},"./pipeline":{"types":"./dist/pipeline/index.d.ts","import":"./dist/pipeline/index.js","default":"./dist/pipeline/index.js"},"./container":{"types":"./dist/container/index.d.ts","import":"./dist/container/index.js","default":"./dist/container/index.js"},"./lifecycle":{"types":"./dist/lifecycle/index.d.ts","import":"./dist/lifecycle/index.js","default":"./dist/lifecycle/index.js"},"./capability":{"types":"./dist/capability/index.d.ts","import":"./dist/capability/index.js","default":"./dist/capability/index.js"},"./observability":{"types":"./dist/observability/index.d.ts","import":"./dist/observability/index.js","default":"./dist/observability/index.js"}},"scripts":{"build":"tsc -p tsconfig.build.json","clean":"rm -rf dist","typecheck":"tsc --noEmit -p tsconfig.json","build:watch":"tsc -p tsconfig.build.json --watch","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"awee","email":"402661910@qq.com"},"repository":{"url":"git+https://github.com/jweelee/aweeclaw.git","type":"git","directory":"packages/harness-core"},"_npmVersion":"11.2.0","description":"AweeClaw Harness Core - AI Agent 驾驭架构核心包，提供管道、中间件、能力注册、可观测性、生命周期管理等通用能力","directories":{},"_nodeVersion":"23.9.0","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/harness-core_1.0.0_1782301186249_0.9789230801479152","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@aweeclaw/harness-core","version":"1.1.0","description":"AweeClaw Harness Core - AI Agent 驾驭架构核心包，提供管道、中间件、能力注册、可观测性、生命周期管理等通用能力","author":{"name":"awee","email":"awee.worker@gmail.com"},"license":"MIT","homepage":"https://github.com/jweelee/aweeclaw","repository":{"type":"git","url":"git+https://github.com/jweelee/aweeclaw.git","directory":"packages/harness-core"},"keywords":["ai-agent","harness","pipeline","middleware","capability","observability","lifecycle","di-container"],"main":"./dist-cjs/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist-cjs/index.js","default":"./dist-cjs/index.js"},"./pipeline":{"types":"./dist/pipeline/index.d.ts","import":"./dist/pipeline/index.js","require":"./dist-cjs/pipeline/index.js","default":"./dist-cjs/pipeline/index.js"},"./capability":{"types":"./dist/capability/index.d.ts","import":"./dist/capability/index.js","require":"./dist-cjs/capability/index.js","default":"./dist-cjs/capability/index.js"},"./observability":{"types":"./dist/observability/index.d.ts","import":"./dist/observability/index.js","require":"./dist-cjs/observability/index.js","default":"./dist-cjs/observability/index.js"},"./lifecycle":{"types":"./dist/lifecycle/index.d.ts","import":"./dist/lifecycle/index.js","require":"./dist-cjs/lifecycle/index.js","default":"./dist-cjs/lifecycle/index.js"},"./container":{"types":"./dist/container/index.d.ts","import":"./dist/container/index.js","require":"./dist-cjs/container/index.js","default":"./dist-cjs/container/index.js"}},"scripts":{"build":"npm run build:esm && npm run build:cjs","build:esm":"tsc -p tsconfig.build.json","build:cjs":"tsc -p tsconfig.cjs.json","build:watch":"tsc -p tsconfig.build.json --watch","clean":"rm -rf dist dist-cjs","typecheck":"tsc --noEmit -p tsconfig.json","prepublishOnly":"npm run clean && npm run build"},"engines":{"node":">=18.0.0"},"devDependencies":{"typescript":"^5.4.0"},"_id":"@aweeclaw/harness-core@1.1.0","bugs":{"url":"https://github.com/jweelee/aweeclaw/issues"},"_nodeVersion":"23.9.0","_npmVersion":"11.2.0","dist":{"integrity":"sha512-bt84o72CHGToeBcWiJbjs03Zx8y9T455ZG5ed/mH8WRI9qDON8rAuzYD02VD1VkHJ8zRxgaQfa85vSgOGJXOnA==","shasum":"66f759191171b8316375df7f1f9a22154f82fe8c","tarball":"https://registry.npmjs.org/@aweeclaw/harness-core/-/harness-core-1.1.0.tgz","fileCount":227,"unpackedSize":325615,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFpVQu2jIehhdH69TMKlxaxlCJXtOcOK2IjHNfQJ2R9pAiEAjmaFkybhcF5vu6WdGVTwa9d9PO7daD4zSu6jrdxFuKk="}]},"_npmUser":{"name":"awee","email":"402661910@qq.com"},"directories":{},"maintainers":[{"name":"awee","email":"402661910@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/harness-core_1.1.0_1782302698448_0.7363587366809308"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-24T11:39:46.147Z","modified":"2026-06-24T12:04:58.756Z","1.0.0":"2026-06-24T11:39:46.391Z","1.1.0":"2026-06-24T12:04:58.629Z"},"bugs":{"url":"https://github.com/jweelee/aweeclaw/issues"},"author":{"name":"awee","email":"awee.worker@gmail.com"},"license":"MIT","homepage":"https://github.com/jweelee/aweeclaw","keywords":["ai-agent","harness","pipeline","middleware","capability","observability","lifecycle","di-container"],"repository":{"type":"git","url":"git+https://github.com/jweelee/aweeclaw.git","directory":"packages/harness-core"},"description":"AweeClaw Harness Core - AI Agent 驾驭架构核心包，提供管道、中间件、能力注册、可观测性、生命周期管理等通用能力","maintainers":[{"name":"awee","email":"402661910@qq.com"}],"readme":"# @aweeclaw/harness-core\n\n> AweeClaw Harness Core - AI Agent 驾驭架构核心包\n\n平台无关的 AI Agent 驾驭架构核心库，提供管道、中间件、能力注册、可观测性、生命周期管理与依赖注入容器等通用能力。可在前端（Electron / Web）、后端（Node.js / NestJS）、移动端（React Native）等多端复用。\n\n## 目录\n\n- [特性](#特性)\n- [安装](#安装)\n- [打包构建](#打包构建)\n- [快速开始](#快速开始)\n- [模块说明](#模块说明)\n  - [Pipeline / Middleware](#pipeline--middleware)\n  - [Capability / CapabilityRegistry](#capability--capabilityregistry)\n  - [Observability](#observability)\n  - [Lifecycle](#lifecycle)\n  - [Container](#container)\n  - [Port（端口抽象）](#port端口抽象)\n- [在客户端 / 后端中接入](#在客户端--后端中接入)\n- [API 速查](#api-速查)\n- [设计原则](#设计原则)\n- [许可证](#许可证)\n\n## 特性\n\n- **平台无关**：纯 TypeScript 实现，不依赖任何运行时（Node / Browser / Electron）\n- **端口抽象**：日志、审计等通过 Port 接口抽象，由使用方注入实现\n- **Tree-shaking 友好**：ESM 输出，按子路径按需引入\n- **零运行时依赖**：仅 TypeScript 作为开发依赖\n- **完整类型定义**：附带 `.d.ts`，IDE 智能提示完备\n- **工业级实现**：完善的异常处理、循环依赖检测、资源释放\n\n## 安装\n\n### 在 AweeClaw 仓库内（Workspace 方式）\n\n在子项目（如 `aweeclaw-client`、`aweeclaw-backend`）的 `package.json` 中添加：\n\n```json\n{\n  \"dependencies\": {\n    \"@aweeclaw/harness-core\": \"workspace:*\"\n  }\n}\n```\n\n然后在仓库根目录执行：\n\n```bash\n# 使用 pnpm\npnpm install\n\n# 或使用 npm workspaces\nnpm install\n```\n\n### 从 npm 安装\n\n```bash\nnpm install @aweeclaw/harness-core\n# 或\npnpm add @aweeclaw/harness-core\n```\n\n## 打包构建\n\n### 前置要求\n\n- Node.js >= 18\n- TypeScript >= 5.4\n\n### 构建命令\n\n```bash\n# 进入包目录\ncd packages/harness-core\n\n# 安装依赖（首次）\nnpm install\n\n# 类型检查\nnpm run typecheck\n\n# 构建（输出到 dist/）\nnpm run build\n\n# 监听模式构建\nnpm run build:watch\n\n# 清理构建产物\nnpm run clean\n```\n\n### 构建产物\n\n构建后 `dist/` 目录结构：\n\n```\ndist/\n├── index.js              # 主入口\n├── index.d.ts            # 主类型定义\n├── index.js.map          # Source Map\n├── index.d.ts.map        # 类型 Source Map\n├── port/                 # 端口抽象\n├── container/            # DI 容器\n├── pipeline/             # 管道与中间件\n├── capability/           # 能力注册\n├── observability/        # 可观测性\n└── lifecycle/            # 生命周期\n```\n\n### 发布到 npm\n\n```bash\n# 1. 更新 package.json 中的 version\n# 2. 登录 npm\nnpm login\n\n# 3. 发布（会自动执行 clean + build）\nnpm publish\n```\n\n## 快速开始\n\n```typescript\nimport {\n  Pipeline,\n  LoggingMiddleware,\n  RateLimitMiddleware,\n  ConsoleLogger,\n  setLogger,\n} from '@aweeclaw/harness-core'\n\n// 1. 设置全局日志实现\nsetLogger(new ConsoleLogger())\n\n// 2. 创建管道\nconst pipeline = new Pipeline<{ toolName: string }, { result: string }>('tool-invocation')\n\n// 3. 注册中间件（按 order 升序执行）\npipeline\n  .use(new RateLimitMiddleware({ maxCalls: 10, windowMs: 1000 }))\n  .use(new LoggingMiddleware())\n\n// 4. 执行\nconst result = await pipeline.execute(\n  { toolName: 'readFile' },\n  async (input) => ({ result: `executed ${input.toolName}` })\n)\nconsole.log(result.result) // \"executed readFile\"\n```\n\n## 模块说明\n\n### Pipeline / Middleware\n\n管道执行器，按中间件 `order` 升序执行 `before` 钩子，执行 handler，再按逆序执行 `after` 钩子。支持 `AbortSignal` 中止。\n\n```typescript\nimport { Pipeline, PipelineContext, type Middleware } from '@aweeclaw/harness-core'\n\n// 自定义中间件\nclass AuthMiddleware<TInput, TOutput> implements Middleware<TInput, TOutput> {\n  readonly id = 'auth'\n  readonly order = 1\n\n  async before(input: TInput, ctx: PipelineContext) {\n    const token = ctx.metadata.token as string\n    if (!token) throw new Error('Unauthorized')\n    return input\n  }\n}\n\nconst pipeline = new Pipeline<Request, Response>('http')\npipeline.use(new AuthMiddleware())\n\nconst response = await pipeline.execute(\n  request,\n  async (req) => handleRequest(req),\n  { token: 'xxx' }\n)\n```\n\n**内置中间件：**\n\n| 中间件 | order | 说明 |\n|--------|-------|------|\n| `ErrorBoundaryMiddleware` | 0 | 错误边界，捕获异常并提供回退值 |\n| `CircuitBreakerMiddleware` | 3 | 熔断器，失败次数达阈值后开路 |\n| `AuditMiddleware` | 5 | 审计记录，可通过 `AuditSink` 持久化 |\n| `LoggingMiddleware` | 10 | 日志记录，记录输入、耗时、错误 |\n| `RateLimitMiddleware` | 15 | 滑动窗口限流 |\n| `RetryMiddleware` | 20 | 指数退避重试 |\n\n### Capability / CapabilityRegistry\n\n能力注册中心，管理 Agent 可调用的原子能力（工具、技能、上下文、MCP 等）。\n\n```typescript\nimport {\n  CapabilityRegistry,\n  type Capability,\n  type CapabilityProvider,\n} from '@aweeclaw/harness-core'\n\n// 实现一个能力\nconst readFileCap: Capability = {\n  id: 'fs.readFile',\n  type: 'tool',\n  name: 'readFile',\n  description: '读取文件内容',\n  version: '1.0.0',\n  metadata: { category: 'filesystem' },\n  async invoke(input, ctx) {\n    const path = input.args.path as string\n    // ...读取文件\n    return { success: true, data: 'file content' }\n  },\n}\n\nconst registry = new CapabilityRegistry()\nregistry.register(readFileCap)\n\n// 查询\nconst tools = registry.query({ type: 'tool' })\n\n// 调用\nconst output = await registry.invoke('fs.readFile', { args: { path: '/tmp/a.txt' } }, {})\n```\n\n**Provider 动态加载：**\n\n```typescript\nclass ToolProvider implements CapabilityProvider {\n  readonly id = 'tool-provider'\n  readonly name = 'Built-in Tools'\n  readonly type = 'tool' as const\n\n  async load(): Promise<Capability[]> {\n    return [readFileCap, writeFileCap]\n  }\n}\n\nawait registry.loadProvider(new ToolProvider())\n```\n\n### Observability\n\n提供链路追踪、指标收集、审计日志、健康检查四类可观测能力。\n\n```typescript\nimport {\n  createSpan,\n  endSpan,\n  MetricCollector,\n  AuditLog,\n  HealthCheckRegistry,\n} from '@aweeclaw/harness-core'\n\n// 链路追踪\nconst span = createSpan('invoke-tool', 'trace-123')\n// ...执行操作\nendSpan(span, 'ok')\n\n// 指标\nconst metrics = new MetricCollector()\nmetrics.increment('tool.invocations', 1, { tool: 'readFile' })\nmetrics.observe('tool.duration', 42, { tool: 'readFile' })\nconst stats = metrics.getHistogramStats('tool.duration', { tool: 'readFile' })\n\n// 审计\nconst audit = new AuditLog()\naudit.record({ action: 'readFile', resource: '/tmp/a.txt', outcome: 'allow' })\n\n// 健康检查\nconst health = new HealthCheckRegistry()\nhealth.register('database', async () => {\n  const ok = await db.ping()\n  return { healthy: ok, checkedAt: Date.now() }\n})\nconst overall = await health.runAll()\n```\n\n### Lifecycle\n\n生命周期管理，按优先级启动 / 停止参与者，支持优雅停机。\n\n```typescript\nimport {\n  LifecycleManager,\n  AbstractLifecycleParticipant,\n  GracefulShutdown,\n} from '@aweeclaw/harness-core'\n\nclass DatabaseParticipant extends AbstractLifecycleParticipant {\n  readonly id = 'database'\n  readonly priority = 10\n\n  async onStart() {\n    await db.connect()\n    this.setPhase('ready')\n  }\n\n  async onStop() {\n    await db.disconnect()\n    this.setPhase('stopped')\n  }\n\n  async onHealthCheck() {\n    return { healthy: await db.ping(), checkedAt: Date.now() }\n  }\n}\n\nconst lifecycle = new LifecycleManager()\nlifecycle.register(new DatabaseParticipant())\n\nawait lifecycle.startAll() // 按 priority 升序启动\n// ...运行\nawait lifecycle.stopAll()  // 按 priority 降序停止\n\n// 优雅停机\nconst shutdown = new GracefulShutdown(15000, () => process.exit(1))\nshutdown.registerTask('flush-queue', '消息队列刷新', flushQueue())\nprocess.on('SIGTERM', () => shutdown.shutdown())\n```\n\n### Container\n\n轻量级依赖注入容器，支持工厂绑定、单例、值绑定、作用域、循环依赖检测。\n\n```typescript\nimport { HarnessContainer, createToken } from '@aweeclaw/harness-core'\n\nconst DbToken = createToken<Database>('db', '数据库连接')\nconst RepoToken = createToken<UserRepository>('user.repo', '用户仓库')\n\nconst container = new HarnessContainer()\n  .singleton(DbToken, () => new Database())\n  .singleton(RepoToken, (c) => new UserRepository(c.resolve(DbToken)))\n\nconst repo = container.resolve(RepoToken)\n\n// 作用域隔离\nconst scope = container.createScope('request-1')\n\n// 释放\nawait container.dispose()\n```\n\n### Port（端口抽象）\n\nharness-core 不绑定任何具体实现，通过 Port 接口由使用方注入。\n\n**LoggerPort：**\n\n```typescript\nimport { setLogger, type LoggerPort } from '@aweeclaw/harness-core'\n\n// 客户端：桥接到 LogEngine\nclass LogEngineAdapter implements LoggerPort {\n  debug(msg, ctx) { logger.agent.debug(msg, ctx) }\n  info(msg, ctx) { logger.agent.info(msg, ctx) }\n  warn(msg, ctx) { logger.agent.warn(msg, ctx) }\n  error(msg, ctx) { logger.agent.error(msg, ctx) }\n}\nsetLogger(new LogEngineAdapter())\n\n// 后端：桥接到 NestJS Logger\nclass NestLoggerAdapter implements LoggerPort {\n  // ...\n}\n```\n\n**AuditSink：**\n\n```typescript\nimport { setAuditSink, type AuditSink } from '@aweeclaw/harness-core'\n\n// 客户端：通过 Electron IPC 持久化\nclass ElectronAuditSink implements AuditSink {\n  async append(entries) {\n    await window.electronAPI.audit.persist(entries)\n  }\n}\nsetAuditSink(new ElectronAuditSink())\n\n// 后端：写入数据库\nclass DbAuditSink implements AuditSink {\n  async append(entries) {\n    await auditRepository.insert(entries)\n  }\n}\n```\n\n## 在客户端 / 后端中接入\n\n### 客户端（aweeclaw-client）\n\n1. 在 `aweeclaw-client/package.json` 添加依赖：\n\n```json\n{\n  \"dependencies\": {\n    \"@aweeclaw/harness-core\": \"workspace:*\"\n  }\n}\n```\n\n2. 在入口处注入端口实现：\n\n```typescript\n// src/renderer/intelligence/harness/bootstrap.ts\nimport { setLogger, setAuditSink } from '@aweeclaw/harness-core'\nimport { logger } from '@toolkit/LogEngine'\n\nsetLogger({\n  debug: (m, c) => logger.agent.debug(m, c),\n  info: (m, c) => logger.agent.info(m, c),\n  warn: (m, c) => logger.agent.warn(m, c),\n  error: (m, c) => logger.agent.error(m, c),\n})\n\nsetAuditSink({\n  async append(entries) {\n    await window.electronAPI.audit.persist(Array.isArray(entries) ? entries : [entries])\n  },\n})\n```\n\n3. 替换原有引用：\n\n```typescript\n// 之前\nimport { Pipeline } from '@renderer/intelligence/harness/pipeline/Pipeline'\n\n// 之后\nimport { Pipeline } from '@aweeclaw/harness-core'\n```\n\n### 后端（aweeclaw-backend）\n\n```typescript\n// src/harness/bootstrap.ts\nimport { setLogger, ConsoleLogger } from '@aweeclaw/harness-core'\n\n// 开发环境用 ConsoleLogger，生产环境桥接到 Pino / Winston\nsetLogger(new ConsoleLogger())\n```\n\n## API 速查\n\n### Pipeline\n\n| API | 说明 |\n|-----|------|\n| `new Pipeline(id)` | 创建管道 |\n| `pipeline.use(middleware)` | 添加中间件 |\n| `pipeline.remove(id)` | 移除中间件 |\n| `pipeline.execute(input, handler, metadata?, signal?)` | 执行管道 |\n| `pipeline.has(id)` | 检查中间件是否存在 |\n\n### Capability\n\n| API | 说明 |\n|-----|------|\n| `new CapabilityRegistry(logger?)` | 创建注册中心 |\n| `registry.register(cap)` | 注册能力 |\n| `registry.resolve(id)` | 按 ID 解析 |\n| `registry.query(filter)` | 按条件查询 |\n| `registry.invoke(id, input, ctx)` | 调用能力 |\n| `registry.loadProvider(provider)` | 加载 Provider |\n\n### Observability\n\n| API | 说明 |\n|-----|------|\n| `createSpan(operation, traceId, parentSpanId?, attrs?)` | 创建 Span |\n| `endSpan(span, status?)` | 结束 Span |\n| `new MetricCollector(maxHistory?)` | 创建指标收集器 |\n| `new AuditLog(maxRecords?)` | 创建审计日志 |\n| `new HealthCheckRegistry()` | 创建健康检查注册表 |\n\n### Lifecycle\n\n| API | 说明 |\n|-----|------|\n| `new LifecycleManager(logger?)` | 创建生命周期管理器 |\n| `lifecycle.register(participant)` | 注册参与者 |\n| `lifecycle.startAll()` | 启动所有 |\n| `lifecycle.stopAll()` | 停止所有 |\n| `new GracefulShutdown(timeoutMs, forceCb?, logger?)` | 创建优雅停机管理 |\n\n### Container\n\n| API | 说明 |\n|-----|------|\n| `new HarnessContainer(parent?)` | 创建容器 |\n| `container.bind(token, factory)` | 绑定工厂 |\n| `container.singleton(token, factory)` | 绑定单例 |\n| `container.value(token, value)` | 绑定常量 |\n| `container.resolve(token)` | 解析依赖 |\n| `container.createScope(id)` | 创建子作用域 |\n| `container.dispose()` | 释放资源 |\n\n## 设计原则\n\n1. **端口与适配器**：核心逻辑只依赖 Port 接口，平台相关实现由使用方注入\n2. **单一职责**：每个模块只做一件事，模块间通过显式依赖关联\n3. **零运行时依赖**：仅 TypeScript 作为开发依赖，产物体积小\n4. **Tree-shaking 友好**：ESM 输出 + 子路径导出，按需引入\n5. **完善的错误处理**：所有异步操作捕获异常，中间件错误不污染主流程\n6. **资源释放**：容器、Provider、LifecycleParticipant 都支持 `dispose`\n\n## 许可证\n\nMIT\n","readmeFilename":"README.md"}