🌐 主仓库在 GitHub — codecloud-dev/agent-core 是唯一主源：Issue、Pull Request、功能讨论请统一提交到 GitHub。Gitee 镜像 仅供国内高速只读访问，每小时从 GitHub 自动同步。

@codecloud-dev/agent-core

通用 Agent 核心 —— 把「元认知协议引擎」与「分级自主护栏」从具体项目里抽出来，做成 平台无关、可注入、可测试的通用代码。适用于运维、研发、数据分析、内容生产、客服、自动化…… 任何需要「会思考 + 可控自治」的 Agent 场景。

🐛 欢迎来“批斗”我

这是个刚起步的项目，bug 肯定有，而且不少。我不装完美—— 你踩到的每一个坑、每一个槽点，都是帮我把它养好的机会。

• 💥 遇到崩溃 / 黑屏 / 跑不起来？→ 提个 Bug 报告
• 💡 有想要的功能？→ 开个需求
• 🗯️ 单纯想吐槽、挑刺？→ 也欢迎开 issue，标签随便打 😄

每个 issue 我都会看，能修的尽快修。一起把它从“能跑”养到“好用” 💪

设计理念：元认知不应该只是一句提示词，而应该是真实跑在引擎里的架构。于是推理链、执行后自检、工具风险分级、单日熔断、影子模式，都做成了可测试的结构化模块——平台无关，任何人都能 npm i 或源码引入，用在自己的 Agent 上。

• 🎯 它解决什么
• 📦 安装
• 🚀 快速开始
• 🛠️ 多种使用方法
• ⚙️ 核心概念
• 🔹 运行时抽象（注入式）
• 📚 完整 API 参考
• 🗺️ 进度表 / 路线图
• ❓ 常见问题（FAQ）
• 🧪 测试
• 💖 支持我们
• 📜 许可

🎯 它解决什么

• 元认知可外显、可强制：think（推理卡）/ reflect（自检卡）是结构化协议动作，引擎能渲染给人类看，并强制"变更后必须先 reflect 才能收尾"。
• 一次吐多个动作不再丢：模型常把 think 和 call 打包成 [{think},{call}]，普通实现会整体落入兜底吞掉 call，导致"只思考不干事"。normalizeActions 把单对象/数组都归一化成动作数组。
• 分级自主护栏：工具三级风险（low/mid/high）+ 单日自动变更熔断 + 影子模式（中危只模拟上报）。让"AI 拿权限"可控、可观测、可回滚。
• 零平台绑定：不依赖 Cloudflare/Node/Vercel。存储、动作执行器、日志都通过接口注入。内置 D1Storage(CF) / MemoryStorage(本地&测试) / NodeStorage(Node 文件) 三个适配器，任意后端（Redis/Prisma/DynamoDB）照模板自写即可。

📦 安装

📦 方式一：源码安装（当前始终可用）

git clone https://github.com/codecloud-dev/agent-core.git
cd agent-core
npm install                 # 仅拉取 esbuild / typescript 等开发依赖
# 打包成单文件（无原生依赖，可直接 require，也可上 Cloudflare Workers 等边缘运行时）
npm run build

📦 方式二：npm 安装（v1.1.0 起已发布）

npm i @codecloud-dev/agent-core

发布状态：包已发布到 npm（version: 1.1.1、prepublishOnly 会自动构建）。直接 npm i 即可安装；文档站与示例均按当前版本编写。

需要打包到边缘运行时（Cloudflare Workers 等）时，用 esbuild/workerd 打包即可（无原生依赖）：

esbuild src/index.ts --bundle --format=esm --outfile=dist/index.js

🚀 快速开始

🔹 1. 元认知：归一化动作 + 闭环门

import { normalizeActions, ReflectGate, buildThink, buildReflect } from '@codecloud-dev/agent-core';

// 模型可能返回单个对象，也可能返回数组（think+call 打包）
const actions = normalizeActions(parsedModelOutput); // Action[]
const gate = new ReflectGate();
for (const a of actions) {
  if (a.action === 'think') renderReasonCard(a.reasoning);
  if (a.action === 'call')  { runTool(a.tool, a.args); gate.afterMutation(); }
  if (a.action === 'reflect') gate.onReflect();
  if (a.action === 'answer') send(a.text);
}
// 收尾前若 gate.isPending → 驳回重做（闭环规则：先自检，再收尾）
if (gate.isPending) reject('请先 reflect 再收尾');

🔹 2. 分级护栏：让自主执行可控

import { guardExecute, defaultRemediationTier, isShadowMode } from '@codecloud-dev/agent-core';
import { MemoryStorage } from '@codecloud-dev/agent-core'; // 本地/测试零依赖；生产换 D1Storage / NodeStorage

const deps = {
  storage: new MemoryStorage(),   // 任何实现 Storage 的都行
  executor: {                    // 真正的自愈动作由你执行
    async execute(tool, args) {
      return await runRemediation(tool, args);
    },
  },
  remediationTier: defaultRemediationTier,
  logger: { log: (lvl, kind, action, detail) => recordAudit(lvl, kind, action, detail) },
};

// 单日额度耗尽 → 直接拦截（blocked），不会真执行
const gate = await checkDailyGate(deps);

// 中危动作：若开了影子模式 → 只模拟上报；否则真执行并计额度
const res = await guardExecute(deps, 'disable_channel', { id: 7 });
if (res.blocked)    alert('今日自动变更额度已耗尽');
else if (res.simulated) reviewLater(res.summary); // 影子模式
else if (res.ok)     console.log('已执行：', res.summary);

跑一个真实可运行的最小示例：

npx tsx examples/quickstart.ts

🛠️ 多种使用方法（从引入到上线）

同一个核心，按你的运行环境选一种接法即可——下面每一种都给可直接抄的片段。

| 场景 | 引入方式 | 存储适配器 | 关键点 | |------|----------|------------|--------| | Node 服务 / CLI | npm i @codecloud-dev/agent-core（ESM）或 require（CJS） | NodeStorage | 文件持久化，零原生依赖 | | 边缘 / Cloudflare Workers | esbuild 打包成单文件 ESM | D1Storage | 无原生依赖，直接上 Workers | | 单元测试 / 本地 | 源码 npx tsx examples/quickstart.ts | MemoryStorage | 零依赖 Mock，跑通即验证 | | Web 框架（Hono / Express） | 作为中间件注入 | 任意 | 请求级隔离，每个请求一个新 Storage |

🔹 1. Node.js：ESM 与 CJS 两种引入

// ESM（推荐，package.json 设 "type": "module"）
import { normalizeActions, guardExecute, MemoryStorage } from '@codecloud-dev/agent-core';

// CJS
// const { guardExecute, MemoryStorage } = require('@codecloud-dev/agent-core');

🔹 2. 边缘运行时：Cloudflare Workers / 无服务器

核心无原生依赖，NodeStorage 只在方法被调用时才 import('node:fs')，Workers 里别用它即可，不影响打包。

// worker.ts
import { guardExecute, D1Storage, defaultRemediationTier } from '@codecloud-dev/agent-core';

export default {
  async fetch(_req: Request, env: { DB: unknown }) {
    const storage = new D1Storage(env.DB as any, { table: 'agent_kv' });
    const res = await guardExecute(
      { storage, executor: myExecutor, remediationTier: defaultRemediationTier },
      'disable_channel', { id: 7 },
    );
    return new Response(JSON.stringify(res));
  },
};

# 打包（产物可直接部署到 Workers / 边缘）
esbuild worker.ts --bundle --format=esm --outfile=dist/worker.js

🔹 3. 单元测试：注入 Mock，不碰真实后端

MemoryStorage 自带 clear()，每个用例前清一次即可隔离；用假 executor 断言护栏行为：

import { guardExecute, MemoryStorage, setShadowMode, defaultRemediationTier } from '@codecloud-dev/agent-core';

const fakeExec = { async execute() { return { ok: true, summary: 'mock' }; } };
const storage = new MemoryStorage();

// 单日额度耗尽 → blocked（不会真执行）
const g1 = await guardExecute({ storage, executor: fakeExec, remediationTier: defaultRemediationTier }, 'add_credits', { uid: 1, amount: 10 });
console.log(g1.blocked);   // true

// 开启影子模式 → 中危只模拟上报
await setShadowMode(storage, true);
const g2 = await guardExecute({ storage, executor: fakeExec, remediationTier: defaultRemediationTier }, 'add_credits', { uid: 1, amount: 10 });
console.log(g2.simulated); // true
storage.clear();

🔹 4. 接入 Web 框架（以 Hono 为例）

import { Hono } from 'hono';
import { guardExecute, D1Storage, defaultRemediationTier } from '@codecloud-dev/agent-core';

const app = new Hono<{ Bindings: { DB: any } }>();
app.post('/agent/act', async (c) => {
  const storage = new D1Storage(c.env.DB, { table: 'agent_kv' });
  const res = await guardExecute(
    { storage, executor: myExecutor, remediationTier: defaultRemediationTier },
    c.req.query('tool')!, await c.req.json(),
  );
  return c.json(res);
});
// Express / Fastify 同理：把 c.env.DB 换成 req.app.locals.db 即可

🔹 5. 端到端：一个「客服补偿」Agent 从零搭

把上面几块串起来就是生产用法：模型一次性吐多个动作 → normalizeActions 归一化 → 变更类动作逐个走 guardExecute 护栏 → ReflectGate 强制「先 reflect 再收尾」→ answer。完整可运行代码见仓库 examples/quickstart.ts，直接跑：

npx tsx examples/quickstart.ts

想换存储后端（Redis / Prisma / DynamoDB）？照 examples/custom-adapter.ts 的 RedisStorage 模板实现 Storage 接口的 getJSON / setJSON 两个方法即可，核心一行不用改。

⚙️ 核心概念

🔹 元认知动作协议

| 动作 | 含义 | 引擎职责 | |------|------|----------| | think | 目标/假设/查证计划/四视角推理 | 渲染成「推理卡」给人类看 | | reflect| 执行后自检（verdict/副作用/更优解/置信度） | 渲染成「自检卡」；ReflectGate 要求它在收尾前出现 | | call | 调工具（带 why 可见思考） | 中危走批准门，高危永远人工确认 | | answer | 自然语言收尾 | 打字机输出 |

think 的 perspectives 固定四视角：决策者 / 用户 / 安全 / 成本——逼 Agent 每次决策都从这四个立场过一遍（拍板的人/受众/风险/资源）。可用 missingPerspectives() 校验四视角是否齐全。

🔹 工具风险分级

type ToolTier = 'low' | 'mid' | 'high';
// low  —— 可逆/无影响（发公告、记记忆）→ 自主可自动
// mid  —— 有业务影响但可逆（加币/会员/调价/踢人）→ 需批准或影子模拟
// high —— 不可逆/高影响（退款/封禁）→ 永远人工确认，不在无人确认下自动执行

defaultToolTier / defaultRemediationTier 是示例策略，接入方必须按自己业务覆盖。

🔹 护栏三件套

1. 单日自动变更熔断（checkDailyGate/bumpDailyGate）：防失控、防自激循环。状态存 Storage，跨请求持久。
2. 影子模式（isShadowMode/setShadowMode）：开启后中危动作只模拟上报不真改，先观察 Agent 决策质量一周再放开。
3. guardExecute 统一包装：所有"自主/无人值守"执行都走它，自动施加熔断 + 影子 + 额度计数。

🔹 运行时抽象（注入式）

核心不 import 任何平台 API。外部依赖通过接口注入：

interface Storage {           // 熔断额度 / 影子开关 都存这
  getJSON<T>(key: string): Promise<T | null>;
  setJSON(key: string, value: unknown): Promise<void>;
}
interface ActionExecutor {    // 真正的自愈动作由外部执行
  execute(tool: string, args: Record<string, any>): Promise<{ ok: boolean; summary: string; data?: unknown; error?: string }>;
}
interface ActionLogger {      // 护栏关键分支回调（可选）
  log?(level: string, kind: string, action: string, detail: string): void | Promise<void>;
}

🔹 内置适配器

| 适配器 | 导入 | 用途 | 依赖 | |--------|------|------|------| | MemoryStorage | @codecloud-dev/agent-core | 本地开发 / 单测 / 演示 / 无状态冷启动 | 零依赖 | | NodeStorage | @codecloud-dev/agent-core | Node 服务 / CLI / 自托管，文件持久化 | 仅用 node:fs（方法调用时才动态加载，不影响 Workers 兼容性） | | D1Storage | @codecloud-dev/agent-core | Cloudflare D1 | Cloudflare 运行时 |

import { MemoryStorage, NodeStorage, D1Storage } from '@codecloud-dev/agent-core';

// 本地 / 测试
const a = new MemoryStorage();

// Node 文件持久化（默认 ./agent-core.kv.json，可用 { file } 指定路径）
const b = new NodeStorage({ file: '/var/lib/agent/kv.json' });

// Cloudflare D1（表名/列名由你传入，核心不写死业务 schema）
const c = new D1Storage(env.DB, { table: 'agent_kv' });

🔹 写自己的 Storage 适配器

核心只认 Storage 接口。以 Redis 为例（完整模板见 examples/custom-adapter.ts）：

import type { Storage } from '@codecloud-dev/agent-core';

class RedisStorage implements Storage {
  async getJSON<T = unknown>(key: string): Promise<T | null> {
    const raw = await redis.get(key);          // 你的后端读取
    if (raw == null) return null;
    return JSON.parse(raw) as T;
  }
  async setJSON(key: string, value: unknown): Promise<void> {
    await redis.set(key, JSON.stringify(value));
  }
}

📚 完整 API 参考

🔹 元认知（metacognition）

| 导出 | 签名 | 说明 | |------|------|------| | normalizeActions | (parsed: unknown) => Action[] | 单对象/数组/空/非法 → 动作数组；过滤 null，空输入返回 [] | | buildThink | (reasoning: ThinkReasoning, text?: string) => ThinkAction | 构造带四视角的 think 动作 | | buildReflect | (input) => ReflectAction | 构造 reflect，confidence 自动夹紧到 0..1 | | isThink / isReflect | (a: unknown) => a is ThinkAction / ReflectAction | 类型守卫 | | missingPerspectives | (r?: ThinkReasoning) => Perspective[] | 检出缺失的视角（用于引擎级把关） | | ReflectGate | class | 闭环门：afterMutation() / onReflect() / isPending / reset() | | isMutationTier | (tier) => boolean | low 之外都算变更（需反思闭环） |

🔹 护栏（guardrails）

| 导出 | 签名 | 说明 | |------|------|------| | ToolTier | 'low' \| 'mid' \| 'high' | 工具风险级别类型 | | TierPolicy | { [tool: string]: ToolTier } | 工具→级别映射 | | defaultToolTier / defaultRemediationTier | TierPolicy | 示例策略（接入方须覆盖） | | getToolTier | (policy, tool) => ToolTier | 查级别，缺省 'mid' | | checkDailyGate | (deps, today?) => Promise<{blocked, remain, cap}> | 单日熔断查询 | | bumpDailyGate | (deps, today?) => Promise<void> | 计数 +1 | | isShadowMode / setShadowMode | (storage, key?) => Promise<boolean> / void | 影子模式开关 | | guardExecute | (deps, action, args, opts?) => Promise<GuardResult> | 统一护栏包装，自动熔断+影子+额度 |

GuardResult：{ ok, summary, simulated, blocked?, data }。

🔤 类型（types）

ActionType、Action、ThinkAction、ReflectAction、CallAction、AnswerAction、 ThinkReasoning、Perspective、ReflectVerdict、Storage、ActionExecutor、ActionLogger。

🔹 适配器（adapters）

D1Storage / D1Like / D1StorageOptions · MemoryStorage · NodeStorage / NodeStorageOptions。

🗺️ 进度表 / 路线图

| 模块 | 状态 | 说明 | |------|------|------| | 元认知协议引擎（think/reflect/normalizeActions/ReflectGate） | ✅ 已发布 | 0.1.0 起 | | 分级护栏（工具分级 / 单日熔断 / 影子模式 / guardExecute） | ✅ 已发布 | 0.1.0 起 | | Cloudflare D1 适配器 | ✅ 已发布 | 0.1.0 起 | | 内存 Storage 适配器 MemoryStorage | ✅ 1.0.0 新增 | 本地开发 / 测试零依赖 | | Node 文件 Storage 适配器 NodeStorage | ✅ 1.0.0 新增 | Node 服务零依赖持久化 | | 可运行开发者示例 examples/ | ✅ 1.0.0 新增 | quickstart / 自定义适配器模板 | | 完整开发者文档 + API 参考 | ✅ 1.0.0 新增 | 本 README | | npm 正式发布 | ✅ 已发布 | @codecloud-dev/agent-core，npm i 即装 | | 更多官方适配器示例（Redis / Prisma / DynamoDB） | ⏳ 规划中 | 欢迎社区贡献 | | 护栏指标 / 可观测性导出 | ⏳ 规划中 | ActionLogger 已留回调口 |

❓ 常见问题（FAQ）

Q：真的能上 Cloudflare Workers 吗？ 能。NodeStorage 只在方法被调用时才动态 import('node:fs')，不用它就不会拉入 Node 依赖；D1Storage 走 env.DB。打包后无原生依赖。

Q：单日熔断的"今天"怎么算？ checkDailyGate / bumpDailyGate 接受 today? 与 now? 注入，便于测试与跨时区。默认用本地日期 YYYY-MM-DD。

Q：高危动作会被自动执行吗？ 不会。guardExecute 只对 mid/low 生效；high 由上层批准门拦截，永远人工确认。

Q：如何重置熔断 / 影子状态？ 直接通过 Storage 删掉对应键（agent:gate / agent:shadow）即可；MemoryStorage 提供 clear()。

🧪 测试

npm test      # esbuild 打包后用内存 Storage mock 跑，全部覆盖全路径

覆盖：① 动作归一化；② 工具分级；③ 单日熔断；④ 影子模式；⑤ guardExecute（熔断拦截 / 影子模拟 / 低危免额度 / 正常执行）；⑥ ReflectGate 闭环；⑦ think/reflect 构造与校验；⑧ MemoryStorage / NodeStorage 往返。

💖 支持我们

如果这个核心帮到了你，欢迎用以下方式支持项目持续维护：

• 💛 爱发电（国内可用，首选）：https://afdian.com/a/cloudharbor —— 国内可直接收款，点个赞助就是最大鼓励。
• ⭐ 在 GitHub 上 Star 本仓库，让更多人发现「可注入、可测试的元认知护栏」。
• 🐛 遇到 bug 或想提需求，欢迎开 Issue 或 PR。

注：GitHub Sponsors 暂不支持中国大陆地区（官方支持约 103 个地区，不含大陆，且需开启两步验证），故国内用户请走上面的爱发电通道。

📜 许可

MIT © mox / codecloud-dev