@epoch-agent/core 0.2.0 → 0.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +29 -28
  2. package/dist/index.d.ts +819 -36
  3. package/dist/index.js +1875 -567
  4. package/package.json +4 -4
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @epoch-agent/core
2
2
 
3
- Agent 引擎。ReAct 循环、Provider 路由、权限、记忆、技能、Hook、Policy、插件、上下文压缩。
3
+ Agent 引擎。ReAct 循环、Provider 路由、权限、记忆、技能、Hook、Policy、内容合规、插件、上下文压缩。
4
4
 
5
5
  - ✅ **做**：领域逻辑
6
6
  - ❌ **不做**：装配（在 [runtime](../runtime)）、命令解析（在 [cli](../cli)）、
@@ -14,33 +14,34 @@ Agent 引擎。ReAct 循环、Provider 路由、权限、记忆、技能、Hook
14
14
 
15
15
  ## 模块
16
16
 
17
- | 目录 | 职责 |
18
- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
- | `agent/` | ReAct 循环（`loop.ts`）、工具执行、实时输出泵、prompt 组装、Nudge / Stall 检测、消息编解码、plan 模式状态、**运行前 token 估算**（`run-estimate.ts`） |
20
- | `provider/` | 多 provider 路由 + 降级、模型元数据探测、AI SDK 适配、**token 估算**（`tokenizer.ts`，全仓唯一口径） |
21
- | `config/` | 10 层配置解析链 + 迁移 + 设置来源分层（`sources.ts`）+ **「为什么是这个值」**（`provenance.ts`，每个键赢在哪一层）+ **「我现在写、写完谁说了算」**（`write.ts`）+ JSON Schema 导出。`schema.ts` 是配置形状的**唯一**真源 |
22
- | `session/` | SQLite 会话持久化 + FTS5 搜索，落盘完整 `EpochMessage`（工具调用 / artifact 引用）+ 逐轮真实用量（`recordUsage`）+ 已批准的计划 + **那一次工作区决定**（v7 两列，见下）。开给模型那一侧的检索 / 前后文窗口 / 血缘在 `query.ts` + `trace.ts`，开给人那一侧的 `@:` 引用（候选 / 解析 / 当前面）在 `reference.ts`，「哪些会话我能读」**两边共用** `authorization.ts` 那一份，索引体检在 `fts-health.ts`（`epoch doctor` 用） |
23
- | `memory/` | 文件 + SQLite 双存储 + 后台审查（`reviewer.ts`） |
24
- | `skill/` | `SKILL.md` 文件系统 + 自动学习（`learner.ts`）。**读正文有两条路，别混**：`view()` 是模型那条（会 `matchCount++`，而那个数喂着有效性评分、也就是模型下次看得见哪些技能），`body()` 是「人点开看一眼」那条（**一个字都不动统计**）—— 一次浏览不是一次命中，判据写在 `SkillSystem.body` 上。**写口只有两个导出**（`previewSkillImport` / `importSkills`，方案 42 §六）：从本机目录导入技能，收路径不收字节，staging 那一层刻意不导出 —— 判据在 `skill/import.ts` 文件头 |
25
- | `hook/` | Hook 匹配与执行、命令执行；`sources.ts` 定「读哪几份配置」（两级 `hooks.json` + **Claude Code 的三份 `settings.json`**，方案 50），`config-loader.ts` 只管解析我们自己的格式，`claude-settings.ts` / `claude-matcher.ts` 只管翻 Claude Code 的方言 |
26
- | `permission/` | 5 级权限（`default` / `acceptEdits` / `plan` / `auto` / `bypass`）+ 审批缓存（`approval-cache.ts`：记弹窗答案；**逐条撤销**走 `revoke(id)` / `PermissionManager.revokeApproval()`，2026-08-27 补 —— 在那之前一次点错的「拒绝」只在内存里、永不过期，除了重启进程收不回来）+ 无头策略 + 紧凑规则 `Tool(content)` + **审计流水**（`audit.ts`：权限层每一次裁决的定长流水，`getAudit()` 取，**只在进程内、永不进遥测**） |
27
- | `workspace/` | 这次会话的地盘：主根 + `--add-dir` 的额外根、目录体检、「哪些指令文件没被加载」，外加「已知工作区」最近使用清单（`~/.epoch/workspaces.json`，**本机文件不是服务**）。判据本身在 infra 的 `isInWorkspace`，这里是壳 |
28
- | `policy/` | 策略文件加载与校验；`sources.ts` 定「扫哪几个 policies 目录」 |
29
- | `context/` | 上下文压缩（工具结果裁剪是**摘要之前的独立一步**，头中尾保留，裁完够了就不调模型；2026-08-16 起认 `compression.*` 两个配置项，见下）、项目发现、指令文件与它的 `@import` 展开 + 项目外放行闸门、artifact 闸门与清理、图片 token 估算、`@` 提及的候选清单与解析（**文件和 `@:` 会话共享同一本 200KB 的账**，方案 53） |
30
- | `sandbox/` | `CodeSandbox`（`code_exec` 的执行器）+ 隔离能力的**对外说法**：`describeIsolation()` 那句中文、以及「哪些工具走沙箱」两份清单。**机制那一半 2026-08-16 搬去了 [infra](../infra) 的 `sandbox/`**（消费者不止 core 一个了，`plugin-terminal` 够不着 core）；既有 import 路径靠再导出保住 |
31
- | `delegate/` | 子 agent 任务委托（`delegate_task` 的后端） |
32
- | `agent-role/` | agent 角色定义、注册与工具作用域收窄（子 agent 和**顶层会话**两条来路走同一个 `roleScopedProvider`）；`createRoleScope` 把它包成**可变槽** —— 身份行和工具表从同一个变量读，好让「这一条消息换个专家」有地方落。⚠️ 2026-08-18 起这里多了一条**写**的路（`create.ts`，全仓第一条建角色的路）：它和读口共用同一份 frontmatter schema、同一个解析器，写完**先读回来验一遍**再落盘。那道「什么样的客户端才准写」的闸门**不在这儿**，在 `@epoch-agent/server`（判据见那个文件头第三节） |
33
- | `extensions/` | 项目级扩展：自定义斜杠命令的发现 / 加载 / 插值 / 按轮次收窄工具表；三种扩展物共用的 frontmatter 解析 |
34
- | `plugin/` | 插件：清单校验、四种来源的安装、安装记录（带跨进程锁）、市场、加载成「六类扩展物的来源」（`PLUGIN_LAYOUT` 那七个约定子路径）。见 [docs/PLUGINS.md](../../docs/PLUGINS.md) |
35
- | `tools/` | `ToolRegistry` + `builtin/` 下那批内置工具（`todo` / `memory` / `goal` / `code_exec` / `run_code` / `delegate_task` / `ask_user_question` / `skill_view` / `tool_search` / plan 模式那两个 / 会话检索那**四个**）。**清单与边界的唯一真源是 [docs/TOOLS.md](../../docs/TOOLS.md)** —— 这里不再抄一个会过期的条数（原来写的「13 个」漏了 `tool_search`） |
36
- | `code-mode/` | `run_code` 的 worker 运行时（方案 51）：线程入口、宿主 ↔ worker 的工具绑定协议、四道上限、只读闸门。⚠️ **和 `sandbox/` 是两回事，隔离模型正好相反** —— 那一个的边界是沙箱，这一个的边界是权限管线（子调用通道本身在 `agent/tool-executor.ts`）。**默认关**，`tools.mode: both` 才注册那个工具 |
37
- | `checkpoint/` | 写类工具动手前的文件快照 + 回退（两阶段原子、不覆盖手工改动）。见 [docs/CHECKPOINTS.md](../../docs/CHECKPOINTS.md) |
38
- | `tracker/` | 待办追踪的 SQLite 表 |
39
- | `schedule/` | 定时任务（方案 45）：store / 单实例锁 / 触发器算术 / 保存期校验 / 录像与留存 / 注册器 / `doctor`，外加 `os/` 下的两个 OS 后端（`schtasks` / `launchd`）。**不含执行器** —— 跑一次要 `buildRuntime()`，那在 [runtime](../runtime) 的 `fireSchedule()` |
40
- | `cost/` | 计价表、预算守卫、花费状态。缓存命中单独计价，口径见 `pricing.ts` 文件头 |
41
- | `compat/` | 竞品词汇表。今天只有 `claude-tool-names.ts`（Claude Code 工具名 ↔ 我们的，双向从同一份数据推出来）—— 放在 `hook/` 之外是因为方案 50 §八 点名的第二个消费者（兼容它的权限规则）不住在 hook 里 |
42
- | `trust/` | 工作区信任判定与闸门 |
43
- | `telemetry/` | span 属性脱敏 |
17
+ | 目录 | 职责 |
18
+ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
19
+ | `agent/` | ReAct 循环（`loop.ts`）、工具执行、实时输出泵、prompt 组装、Nudge / Stall 检测、消息编解码、plan 模式状态、**运行前 token 估算**（`run-estimate.ts`） |
20
+ | `provider/` | 多 provider 路由 + 降级、模型元数据探测、AI SDK 适配、**token 估算**（`tokenizer.ts`，全仓唯一口径） |
21
+ | `config/` | 10 层配置解析链 + 迁移 + 设置来源分层（`sources.ts`）+ **「为什么是这个值」**（`provenance.ts`，每个键赢在哪一层）+ **「我现在写、写完谁说了算」**（`write.ts`）+ JSON Schema 导出。`schema.ts` 是配置形状的**唯一**真源 |
22
+ | `session/` | SQLite 会话持久化 + FTS5 搜索，落盘完整 `EpochMessage`（工具调用 / artifact 引用）+ 逐轮真实用量（`recordUsage`）+ 已批准的计划 + **那一次工作区决定**（v7 两列，见下）。开给模型那一侧的检索 / 前后文窗口 / 血缘在 `query.ts` + `trace.ts`，开给人那一侧的 `@:` 引用（候选 / 解析 / 当前面）在 `reference.ts`，「哪些会话我能读」**两边共用** `authorization.ts` 那一份，索引体检在 `fts-health.ts`（`epoch doctor` 用） |
23
+ | `memory/` | 文件 + SQLite 双存储 + 后台审查（`reviewer.ts`） |
24
+ | `skill/` | `SKILL.md` 文件系统 + 自动学习（`learner.ts`）。**读正文有两条路，别混**：`view()` 是模型那条（会 `matchCount++`，而那个数喂着有效性评分、也就是模型下次看得见哪些技能），`body()` 是「人点开看一眼」那条（**一个字都不动统计**）—— 一次浏览不是一次命中，判据写在 `SkillSystem.body` 上。**写口只有两个导出**（`previewSkillImport` / `importSkills`，方案 42 §六）：从本机目录导入技能，收路径不收字节，staging 那一层刻意不导出 —— 判据在 `skill/import.ts` 文件头 |
25
+ | `hook/` | Hook 匹配与执行、命令执行；`sources.ts` 定「读哪几份配置」（两级 `hooks.json` + **Claude Code 的三份 `settings.json`**，方案 50），`config-loader.ts` 只管解析我们自己的格式，`claude-settings.ts` / `claude-matcher.ts` 只管翻 Claude Code 的方言 |
26
+ | `permission/` | 5 级权限（`default` / `acceptEdits` / `plan` / `auto` / `bypass`）+ 审批缓存（`approval-cache.ts`：记弹窗答案；**逐条撤销**走 `revoke(id)` / `PermissionManager.revokeApproval()`，2026-08-27 补 —— 在那之前一次点错的「拒绝」只在内存里、永不过期，除了重启进程收不回来）+ 无头策略 + 紧凑规则 `Tool(content)` + **审计流水**（`audit.ts`：权限层每一次裁决的定长流水，`getAudit()` 取，**只在进程内、永不进遥测**） |
27
+ | `workspace/` | 这次会话的地盘：主根 + `--add-dir` 的额外根、目录体检、「哪些指令文件没被加载」，外加「已知工作区」最近使用清单（`~/.epoch/workspaces.json`，**本机文件不是服务**）。判据本身在 infra 的 `isInWorkspace`，这里是壳 |
28
+ | `compliance/` | **内容合规闸门**：本地词表 + 正则。**缺省只拦用户输入**（送进模型之前，命中 block 时请求不发也不计费）；模型输出那一侧同一套东西都在（`agent/turn.ts` 那个唯一出口 + 句子级 holdback），一行配置就能开，但缺省关 —— 它是误伤和流式延迟的大头，判据在 `settings.ts`。变体归一化（全角 / 零宽 / 分隔符 / leet / 繁简，**带 offset 映射**因为 `mask` 要打回原文）、Aho-Corasick 多模式匹配、豁免表（治「`台独` 命中『平**台独**立部署』」那一类）、句子级 holdback 的流式 guard。**缺省跳过代码**（围栏块与行内 code）—— 这是个写代码的 agent，那一格决定这层能不能用。类别 / 动作两个联合住 [protocol](../protocol)（它们同时是配置键名、词库文件名、遥测属性值）。**内置词表是种子不是生产词库**，正式部署挂 `~/.epoch/compliance/<类别>.txt` |
29
+ | `policy/` | 策略文件加载与校验；`sources.ts` 定「扫哪几个 policies 目录」 |
30
+ | `context/` | 上下文压缩（工具结果裁剪是**摘要之前的独立一步**，头中尾保留，裁完够了就不调模型；2026-08-16 起认 `compression.*` 两个配置项，见下）、项目发现、指令文件与它的 `@import` 展开 + 项目外放行闸门、artifact 闸门与清理、图片 token 估算、`@` 提及的候选清单与解析（**文件和 `@:` 会话共享同一本 200KB 的账**，方案 53） |
31
+ | `sandbox/` | `CodeSandbox`（`code_exec` 的执行器）+ 隔离能力的**对外说法**：`describeIsolation()` 那句中文、以及「哪些工具走沙箱」两份清单。**机制那一半 2026-08-16 搬去了 [infra](../infra) 的 `sandbox/`**（消费者不止 core 一个了，`plugin-terminal` 够不着 core）；既有 import 路径靠再导出保住 |
32
+ | `delegate/` | 子 agent 任务委托（`delegate_task` 的后端） |
33
+ | `agent-role/` | agent 角色定义、注册与工具作用域收窄（子 agent 和**顶层会话**两条来路走同一个 `roleScopedProvider`）；`createRoleScope` 把它包成**可变槽** —— 身份行和工具表从同一个变量读，好让「这一条消息换个专家」有地方落。⚠️ 2026-08-18 起这里多了一条**写**的路（`create.ts`，全仓第一条建角色的路）：它和读口共用同一份 frontmatter schema、同一个解析器，写完**先读回来验一遍**再落盘。那道「什么样的客户端才准写」的闸门**不在这儿**，在 `@epoch-agent/server`（判据见那个文件头第三节） |
34
+ | `extensions/` | 项目级扩展：自定义斜杠命令的发现 / 加载 / 插值 / 按轮次收窄工具表；三种扩展物共用的 frontmatter 解析 |
35
+ | `plugin/` | 插件：清单校验、四种来源的安装、安装记录（带跨进程锁）、市场、加载成「六类扩展物的来源」（`PLUGIN_LAYOUT` 那七个约定子路径）。见 [docs/PLUGINS.md](../../docs/PLUGINS.md) |
36
+ | `tools/` | `ToolRegistry` + `builtin/` 下那批内置工具（`todo` / `memory` / `goal` / `code_exec` / `run_code` / `delegate_task` / `ask_user_question` / `skill_view` / **技能写入那四个** / `tool_search` / plan 模式那两个 / 会话检索那**四个**）。**清单与边界的唯一真源是 [docs/TOOLS.md](../../docs/TOOLS.md)** —— 这里不再抄一个会过期的条数（原来写的「13 个」漏了 `tool_search`） |
37
+ | `code-mode/` | `run_code` 的 worker 运行时（方案 51）：线程入口、宿主 ↔ worker 的工具绑定协议、四道上限、只读闸门。⚠️ **和 `sandbox/` 是两回事，隔离模型正好相反** —— 那一个的边界是沙箱，这一个的边界是权限管线（子调用通道本身在 `agent/tool-executor.ts`）。**默认关**，`tools.mode: both` 才注册那个工具 |
38
+ | `checkpoint/` | 写类工具动手前的文件快照 + 回退（两阶段原子、不覆盖手工改动）。见 [docs/CHECKPOINTS.md](../../docs/CHECKPOINTS.md) |
39
+ | `tracker/` | 待办追踪的 SQLite 表 |
40
+ | `schedule/` | 定时任务（方案 45）：store / 单实例锁 / 触发器算术 / 保存期校验 / 录像与留存 / 注册器 / `doctor`，外加 `os/` 下的两个 OS 后端（`schtasks` / `launchd`）。**不含执行器** —— 跑一次要 `buildRuntime()`，那在 [runtime](../runtime) 的 `fireSchedule()` |
41
+ | `cost/` | 计价表、预算守卫、花费状态。缓存命中单独计价，口径见 `pricing.ts` 文件头 |
42
+ | `compat/` | 竞品词汇表。今天只有 `claude-tool-names.ts`（Claude Code 工具名 ↔ 我们的，双向从同一份数据推出来）—— 放在 `hook/` 之外是因为方案 50 §八 点名的第二个消费者（兼容它的权限规则）不住在 hook 里 |
43
+ | `trust/` | 工作区信任判定与闸门 |
44
+ | `telemetry/` | span 属性脱敏 |
44
45
 
45
46
  另外 10 个工具在四个 plugin 里，不在这里：见
46
47
  [plugin-file](../plugins/plugin-file) / [plugin-terminal](../plugins/plugin-terminal) /