生成事实图 wind342/dsh-gfg

面向 DeepSeek Harness 的 GFG

一个轻量级的生成事实图，用于追踪 agent 动作和工具结果究竟是如何形成的。

Final Tool Result
↑
Execution Occurrence
↑
Effective Tool Action
↑
Pre-execute / Policy
↑
Original Tool Call
↑
Assistant Message Settlement

这不是日志关联。 关系是从具体的运行时事件中捕获的，并作为精确的生成事实予以保留。这是生成溯源，而非对因果解释的断言，也不代表可以访问模型内部推理。

gfg_trace({"target_id":"read-1"}) 返回一个结构化的生成子图。
普通工具结果不携带任何附加的 GFG 元数据。

生成示意图

试用演示

需要 Node 24+、pnpm，以及固定版本的 Harness 0.2.0-rc.2 包。

git clone https://github.com/wind342/dsh-gfg.git
cd dsh-gfg
pnpm install --frozen-lockfile
pnpm build
pnpm check
pnpm test
pnpm demo

该演示使用真实、未经修改的 Harness AgentLoop、会话存储和工具运行时，并配合一个脚本化的 LLM 适配器以保证可重复性；无需 API 密钥。
Agent 会派发一个真实的文件读取工具，收到 hello，然后派发 gfg_trace。第二个会话演示了策略拒绝且零工具主体调用的情况。
脚本会检查普通输出在捕获关闭/开启时的相等性。这不是远程 DeepSeek 模型测试，也不是产品 CLI 启动器。

已提交的合成示例：

- 演示结果
- 读取文件图 / 追踪
- 被拒绝的图 / 追踪

在 Harness 配置文件中安装

在本地构建一个包（未发布到 npm）：

pnpm pack
dsh plugin --profile headless add /absolute/path/to/dsh-gfg-0.1.0.tgz
dsh --profile headless "Read a.txt, then use gfg_trace with the read tool's call ID to inspect how its result formed."

该包声明了 dsh.bundle 并包含 cordis.patch.yml，因此配置文件插件管理器可以启用其对应行。请使用官方的 dsh 启动器，而不是单独自制的应用引导程序。在 Harness 本身中设置你的模型提供方/凭据。
官方 CLI 0.2.0-rc.2 的配置文件安装冒烟测试也可在没有提供方的情况下运行：它会打包此插件，使用 dsh plugin 安装该 tarball，检查已启用的 bundle 和 --dump-config 行，并通过官方启动器启动一个最小配置文件，直到其应用就绪回调观察到 GFG 服务。
实际提供方在此处仍未经验证。
不要在其他 Harness 版本上悄悄覆盖固定的兼容范围。

使用独立安装的官方 CLI 运行 pnpm profile:smoke /absolute/path/to/@deepseek-ai/dsh/lib/bin.js。
该冒烟测试使用一个全新的、被忽略的 .profile-smoke/ 主目录，而不是你真实的 Harness 配置文件。它会把失败记录为 product_cli_profile_test: false；仅打包本身并不算配置文件 PASS。
实际 CLI 冒烟结果 包含由 pnpm verify 检查的源哈希，用于检测过期的证据。

该 tarball 已单独安装到一个隔离的包目录中，其注册的工具通过 node examples/package-smoke.mjs 进行了测试。该检查从已安装的包加载依赖，而非从源代码检出加载。

profile 的 cordis.patch.yml 中的可选覆盖：

- id: dsh-gfg
config:
directory: /absolute/private/path/to/gfg

默认情况下，每个进程/会话在 ~/.dsh/gfg/ 下都有一个全新的运行目录。它包含仅追加的 receipts.jsonl 以及一个在 Harness 会话刷新和插件处置时写入的 gfg.json 快照。回执写入是同步的；会话刷新还会调用 fsync。仅内存模式由测试使用，而非默认 profile。

原始回执可能包含私有提示词、文件内容、参数和结果。
请保持该目录私有，检查操作系统 ACL（尤其是在 Windows 上），并且切勿自动发布真实用户的图。此处仅提交公共 fixture 产物。

模型可调用的工具

{"target_id":"read-1", "direction":"backward", "max_depth":32}

- gfg_trace：向后/向前局部图遍历；返回 nodes、edges、formation_path、evidence_refs、target、direction、complete 和 truncated。
- gfg_get_node({"id":"..."})：一个确切节点的结构投影。

两个查询都使用正向字段允许列表。它们从不返回原始回执/节点负载、规范值、参数、元数据或错误文本，包括被 post-execute 策略隐藏的数据。回执引用保留 ID/SHA-256、证据可用性和 payload_visibility: "private"。完整证据保留在私有日志和内部 RuntimeGFG 中，保持不变。没有模型可调用的原始负载选项。
简单读取演示的紧凑 JSON 跟踪为 30,792 字节，而同一内部完整回执跟踪为 44,055 字节（约小 30%）；图节点和边均被保留。这不是一种压缩图协议。

目标可以是 fact/occurrence/outcome ID、持久工具结果消息 ID，或原始提供方工具调用 ID。result: 寻址持久结果存在之前的最终运行时结果。重用的别名会产生 AMBIGUOUS_TARGET；它们绝不会通过猜测最新结果来解决。请改用确切的节点 ID。
查询的作用域限定为调用会话；没有模型控制的 run_id。
查询工具本身被排除在捕获之外，以避免递归存储图。

捕获的内容

| Harness 边界 | 记录的材料 |
| 带工具调用的 assistant/message | 完整的持久事件、流和提议的调用块 |
| assistant/attempt | 带有显式 no_surface_message 处置的流 |
| tool/call | 完整的持久事件、原始原始参数字符串 |
| tools/pre-execute | 观察到的条目和实际策略决策 |
| tools/execute | 观测到的分发入口与规范化后的返回结果 |
| tools/post-execute | 传入结果与实际的下游决策 |
| tools/result | 权威的冻结结果，包括结构化的 value |
| tool/result | 完整的、面向模型的持久事件 |

入口观测代表实际的中间件调用，而非臆造的工具效果。身份绑定使用原生调用 ID 和注册表的不透明执行令牌；嵌套分发使用实际的父令牌。不根据时间戳、文本相似度或邻近性推断任何关系。运行时句柄（agent/context/functions、私有 schema 与取消对象）不会被序列化；其相关的身份与信号状态会被记录。原生 JSON 参数与结果完整保留。

拒绝、取消、执行失败、抑制与未观测到的结算均为 ExplicitDisposition。缺失的上游历史会成为显式的来源记录，而非捏造的阶段。捕获失败时，普通结果仍会通过；图会被标记为不完整，查询工具拒绝将其呈现为完整。没有观测到 tools/execute 的错误会被保守地归类为 policy_or_pre_dispatch_unobserved，除非有已知的拒绝/取消/未执行分类可用。绝不会猜测为 execution_failed。

图结构

每个事实保留 (origin, transform, occurrence, outcome; relation_role)，外加 fact_id、run_id、sequence 和 receipt_sha256。

Source / GeneratedOrigin → OccurrenceNode ──realizes_fact──→ FactNode → Outcome
│
next GeneratedOrigin ←──────────────────────────┘

实际的延续是 Outcome → GeneratedOrigin → next occurrence/fact。编译器只使用提供的绑定。多来源/多结果事件不会变成笛卡尔积。即使事实共享同一个 occurrence，遍历也会遵循事实特定的 origin 绑定。formation_path 是带深度的 BFS 访问顺序；定义形成关系的是边，而不是该数组中相邻的行。

规范 JCS + SHA-256 标识收据、事实和图快照。schema 是 dsh-gfg/jcs/1，不是 Core-v3 的 Python wire/hash 格式。离线验证器检查哈希、引用、收据序列/链、别名和重新编译。它不会在每次查询时验证整个图。索引是增量的，查询只访问所请求的邻域；没有全局传递闭包。

测试与实测开销

pnpm test 覆盖普通输出不变性、真实 AgentLoop 形成、被拒绝/失败/取消的调用、显式缺失结果、多来源精确绑定、并发、嵌套、重复 ID、会话隔离、字节级一致的确定性图、日志重放、篡改和捕获失败。pnpm check 对产品和 fixtures 都进行类型检查。
回归测试还覆盖策略后的密钥脱敏（包括仅内容脱敏）、零正文调用的单调守卫拒绝、未观测到的派发前失败，以及内部证据不变的紧凑查询大小。
GitHub Actions 在 Node 24 上运行冻结安装、构建、类型检查、测试、演示和验证。单独记录的真实 CLI 冒烟测试与源哈希绑定。

运行 pnpm test:report && pnpm demo && pnpm verify 以重新生成机器可读的
检查和测试结果。

pnpm benchmark 对每种模式运行 3 × 500 次合成的零 I/O 工具调用。在记录的
Windows/i5-12490F 运行中，每次调用的中位时间约为 0.21 ms OFF、 0.70 ms 内存捕获和 0.85 ms 日志捕获。本地跟踪约为 0.21–0.27 ms，覆盖一个包含 3,000 个事实的图。这些数字不包括 LLM 时间、设置、最终快照和离线验证；fsync 单独报告。
这是可测量的开销，并非免费捕获或生产吞吐量声明。
所有样本和范围。

范围和限制

- 此 v1 观察暴露的运行时边界，而非提供程序内部、任意工具主体文件依赖或每次私有重试尝试。绕过我们监听器的外部中间件不在该监听器的捕获范围内。在工作开始前加载；不对未观测事件进行追溯推断。
- 原生工具模式已端到端演练。显式父令牌嵌套已测试；PTC 特定的持久桥接事件和子代理跨会话联接尚未实现。不声称完整的 PTC/主体级数据流。
- 观察者成本可能影响墙钟时间和超时敏感行为。注册查询工具会改变工具目录；确定性普通输出不变性并不意味着随机模型决策不变。
- 完整回执消耗的 RAM/磁盘与捕获的有效载荷大小成正比。没有自动保留/删除、压缩或后台上传。
- 不完整/撕裂的日志可被检测到，但攻击者重写所有记录和哈希时，若无单独受信任的根则无法抵御。这些哈希是完整性标识，而非签名或运行时真实性的证明。
- 进程突然终止可能省略最终快照/关闭处置；恢复的日志是捕获的前缀，而非已完成执行的证明。
- 严格 JSON 边界会拒绝非 JSON 对象、循环、孤立代理项、非有限数字和不安全整数，而不是静默地对其汇总。

来源和许可证

独立的 Apache-2.0 插件；不是官方 DeepSeek 产品。复用官方 Harness 服务和现有 GFG 组织，不导入私有研究代码或重型 Core-v3 验证器。复用/许可证审计。

完整研究证据保留在单独的冻结的研究证据仓库。
公开的 GFG Core 提取也是独立的。本插件不会更改任何仓库或任何冻结标签。

准备好的 Discussion 帖子——不会自动发布。