name: ghost description: 从现有仓库创建一个语言无关的幽灵包（规范+便携测试），通过提取SPEC.md、详尽的tests.yaml（操作和/或场景）、INSTALL.md、README.md、VERIFY.md以及上游LICENSE文件，包含来源和再生指令。当提示提到"$ghost"、“ghostify此仓库”、“spec-ify/spec-package此库”、“幽灵库”，或要求为库或工具使用代理循环（场景测试）提取便携规范/测试时使用；不要用于实现工作或编辑技能。

ghost

概述

从现有仓库生成一个幽灵包（规范+测试+安装提示）。

保留行为，而非文本：

tests.yaml是行为契约（操作案例和/或场景）
源测试和/或捕获的痕迹是主要证据
代码/文档/示例仅填补空白（绝不与证据矛盾）

输出是语言无关的，因此可以在任何目标语言或框架中实现。

场景测试框架（用于代理系统/工具循环）：

给定一个初始世界状态+工具表面+用户目标
当代理在现实约束和噪声下运行
那么它达到可接受的结果，不违反不变量（安全、安全、成本、延迟、策略）

适用性/限制

当系统的行为可以表达为确定性数据时，这种方法效果最佳：

纯操作（输入->输出或错误）
覆盖公共API的可运行测试套件

它也适用于代理系统，当行为可以表达为可控、可重放的场景时：

工具沙盒（存根/记录重放/模拟器）
机器可检查的预言机（状态断言+痕迹不变量）
确定性调试模式加类似生产的可靠性模式（通过率）

当契约依赖于时间、随机性、IO、并发、全局状态或平台细节时，它会变得更难（但仍然可能）。在这些情况下，在SPEC.md + VERIFY.md中明确假设，并将非确定性规范化为显式输入/输出。

硬规则（必须/必须不）

必须将上游测试（对于代理系统：捕获的痕迹/评估运行）视为权威；如果文档/示例有分歧，优先证据并记录差异。
必须将环境/工具表面的非确定性规范化为显式输入/输出（无隐式“现在”、随机种子、本地化意外、无序迭代）。
必须使模型/代理的随机性显式，并将其测试为可靠性：以通过率+无违反不变量运行为门限（非精确文本黄金标准）。
必须保持幽灵仓库语言无关：不交付实现代码、适配运行器或构建工具。
必须转述上游文档；不逐字复制文本。
必须逐字保留上游许可证文件为LICENSE*。
必须产生验证信号并在VERIFY.md中记录（适配运行器优先；采样回退允许）。
必须在VERIFY.md中记录来源和再生（上游仓库+修订、如何生成工件、如何重新运行验证）。
必须选择匹配系统风格的tests.yaml契约形状（功能性API vs 协议/CLI vs 场景），并在SPEC.md、INSTALL.md和VERIFY.md中保持一致。
当tests.yaml非平凡时（回调、变异步骤、警告、多步骤协议设置等），必须记录其框架模式。
- 推荐工件：TESTS_SCHEMA.md。
- INSTALL.md必须在存在时引用它。
必须最小化skip案例；仅在确定性设置当前不可行时跳过，并记录原因。
必须显式断言稳定机器接口字段（必需键、长度/计数和状态效果），不仅仅是松散部分匹配。
必须将人类可读警告/错误消息视为不稳定，除非测试证明它们是公共契约的一部分。
- 优先结构化字段（代码）或子字符串断言用于消息检查。
当行为依赖于先前调用时（例如会话、实例、历史或工具循环连续性），必须捕获跨操作状态转换。
必须包含每个主要状态化工作流的可执行端到端循环覆盖（例如创建->操作->持久化->后续），具有显式前后状态断言。
如果仅存在孤立操作案例，必须将状态化工作流视为不完整；在tests.yaml中添加场景覆盖和验证证明，然后称提取完成。
必须包含代理场景的痕迹级不变量（例如权限边界、副作用前确认、注入抵抗、预算/步骤限制）。
必须优先通过状态+痕迹（工具调用、副作用）评分行为的预言机，而非脆弱的最终文本匹配。
必须在verification/evidence/下产生机器可检查的证据包，并且除非通过uv run python scripts/verify_evidence.py --bundle <ghost-repo>/verification/evidence，否则提取失败。
必须执行失败关闭验证门限：100%映射的公共操作、100%映射的主要工作流、变异敏感门通过和独立再生奇偶性通过。

输入

源仓库路径（git工作树）
输出仓库名称/位置（默认：同级目录<repo-name>-ghost）
上游身份+修订（如果可用远程URL；标签/提交SHA）
公共表面如果不明确：
- 库：函数/类/模块
- 代理系统：工具名称/模式、权限和副作用边界
源语言/运行时+如何运行上游测试
任何必需的运行时假设（时区、本地化、单位、编码）

对于场景密集（代理）提取，还需收集：

场景目录（顶级用户目标+失败模式）
工具错误/延迟行为（超时、500错误、畸形载荷）
显式不变量（安全、安全、成本、延迟、策略）

约定

操作ID

tests.yaml按操作ID（公共API条目的稳定标识符）组织案例。使用跨语言翻译中存活的命名方案：

foo（顶级函数）
module.foo（命名空间函数）
Class#method（实例方法）
Class.method（静态/类方法）

避免ID中的语言特定拼写（例如，避免snake_case vs camelCase争议）。优先源库文档使用的规范名称。

对于代理场景套件，操作ID应与代理看到的工具名称匹配（例如orders.lookup、tickets.create）。

场景ID

当使用场景测试时，保持场景ID稳定和描述性：

refund.create_ticket_with_guardrails
calendar.reschedule_with_rate_limit
security.prompt_injection_from_tool_output

契约形状

选择一个模式并保持一致：

功能性API布局：顶级操作ID，带有{name,input,output|error}案例。
协议/CLI布局：顶级meta + operations，其中操作ID位于operations下，案例包括命令/状态断言。
场景布局（代理系统）：顶级meta + scenarios，其中场景ID位于scenarios下，每个场景定义环境+工具+目标+预言机。

`tests.yaml`版本

tests.yaml必须包含将案例绑定到上游证据的源版本标识符。

如果上游库有发布版本（SemVer/标签），使用它。
否则，使用不可变源修订标识符（例如git:<short-sha>或git describe）。
功能性布局：使用顶级version。
协议/CLI布局：为测试模式版本保留meta.version，并为上游证据版本包括meta.source_version。
场景布局：为模式版本保留meta.version，并为上游证据版本包括meta.source_version。

工作流（测试优先）

0) 定义范围和契约

写一个一行问题陈述，命名上游仓库/修订和目标幽灵输出路径。
选择一个tests.yaml布局（功能性、协议/CLI或场景），并在SPEC.md、INSTALL.md和VERIFY.md中保持一致。
设置成功标准：每个公共操作的确定性案例、主要状态化工作流的可执行循环覆盖，以及VERIFY.md中记录的验证信号。

对于代理系统，定义成功标准为：

在受控工具沙盒中表达的关键场景
硬预言机+痕迹级不变量（无关键违反）
类似生产运行的可靠性门（通过率门限）

1) 范围化源

定位测试套件、示例和主要文档（README、API文档、文档站点）。
识别公共API并将每个公共操作映射到操作ID。
使用导出/可见性提示确认公共内容：
- JS/TS：包入口点+导出/重新导出
- Python：顶级模块+__all__
- Rust：lib.rs中重新导出的pub项
- Zig：build.zig模块图（root_source_file、addModule、pub usingnamespace）是真相源；默认通常是src/root.zig（库）和src/main.zig（可执行文件）但仓库各异；仅当文档化为API时才将C ABI export视为公共
- C/C++：安装的公共头文件+导出符号；仅当文档化为API时才包括宏/常量
- Go：导出标识符（大写）
- Java/C#：目标包/命名空间中的public类型/成员
- 其他：使用语言的可见性/导出机制+发布的包入口点
确认哪些函数/类在范围内：
- 公共API+覆盖它的测试
- 排除内部助手，除非测试证明它们是契约的一部分
识别主要用户面对的工作流（尤其是状态化循环），并将每个工作流映射到所需操作序列和状态边界。

对于代理系统：

识别工具表面（名称、模式、权限、速率限制）。
识别环境/状态（工具调用时什么变化）。
识别必须在整个痕迹中保持的不变量（安全/安全/成本/延迟/策略）。
构建覆盖矩阵（功能性、鲁棒性、安全/安全/滥用、成本/延迟）。
除非用户覆盖，否则决定输出目录为新同级仓库。

2) 收获行为证据

提取测试案例和预期输出（或场景痕迹）；将证据视为权威。
当测试无声时，阅读代码/文档推断行为并记录推断。
注意所有边界值、舍入规则、编码规则和错误案例。
如果API承诺“复制”/“分离”行为，收获变异隔离证据（包括嵌套结构变异，不仅仅是顶级字段）。
对于状态化API，跨步骤收获连续性证据（持久化ID、历史链、上下文/工具携带和重置语义）。
规范化环境假设：
- 消除对当前时间的依赖（使用显式时间戳）
- 如果相关，强制时区/本地化规则
- 移除非确定性（随机种子、无序迭代）

对于场景套件，还需收获：

现实工具失败（超时/500错误/畸形JSON/部分结果）和回退/重试行为
类似提示注入的工具输出和所需拒绝/忽略行为
停止条件（最大步骤、预算）和优雅暂停

3) 写`SPEC.md`（严格，语言无关）

抽象描述类型（数字/字符串/对象/时间戳/字节等）。
对于字节/缓冲区，定义规范编码（十六进制或base64）并在tests.yaml中一致使用。
定义规范化规则（例如，时间戳解析、字符串修剪、Unicode、大小写折叠）。
精确指定错误行为（条件），但保持机制语言惯用。
用输入、输出、规则和边缘案例指定每个公共操作。
当操作产生“准备”值和“持久化增量”（或类似）时，机械定义增量推导（切片/过滤器/身份规则）并测试它。
为主要工作流指定跨操作不变量（状态转换、所需顺序和连续性保证）。
对于场景，指定：
- 环境状态模型和重置语义
- 工具表面契约（模式、权限、速率限制）
- 作为显式、可测试规则的不变量（痕迹级）
转述源文档；不逐字复制文本。
使用references/templates.md获取结构。

4) 生成`tests.yaml`（详尽）

将每个源测试转换为其操作ID下的YAML案例。
包括源版本标识符（version或meta.source_version）。
模式故意严格和便携；从约定中选择契约形状：
- 功能性布局：
  - 每个案例有name和input
  - 每个案例正好有output或error: true之一
- 协议/CLI布局：
  - 顶级meta + operations
  - 每个案例有name、input和确定性预期结果（例如exit_code、机器可读stdout断言和状态断言）
- 保持便携YAML子集（无锚点/标签/二进制），以便在许多语言中容易解析
- 引用模糊标量（yes、no、on、off、null）以避免解析器分歧
规范化输入为确定性值（避免“现在”；使用显式时间戳）。
保持或改进覆盖所有公共操作和失败模式。
为主要状态化工作流添加场景案例，以便契约证明端到端循环行为，不仅仅是每操作正确性。
对于代理系统，优先场景布局，并将每个场景定义为：
- 初始状态（代理知道什么+世界状态）
- 工具沙盒（存根/记录重放/模拟器）和权限
- 动态（世界如何响应工具调用，包括失败/延迟）
- 成功标准（最终状态和/或所需工具副作用）
- 预言机（硬断言+痕迹不变量；可选评分判断）
为稳定输出字段优先精确/值完整断言；仅当字段有意不稳定时才使用部分断言。
对于警告/错误消息检查，优先子字符串断言，除非确切措辞本身是上游契约的一部分。
如果tests.yaml包括基本{name,input,output|error}之外的框架指令（例如按标签回调、变异步骤、警告接收器、设置脚本），在TESTS_SCHEMA.md中记录它们。
保持skip罕见；每个跳过必须包括具体原因并在VERIFY.md中说明。
如果源返回浮点数，优先定义稳定舍入/格式化规则，以便output精确。
遵循references/templates.md中的格式。

5) 添加`INSTALL.md` + `README.md` + `VERIFY.md` + `LICENSE*`

INSTALL.md：一个简短提示，用于在任何语言中实现库，引用SPEC.md和tests.yaml。
README.md：解释幽灵库是什么，列出操作，并描述包括的文件。
TESTS_SCHEMA.md（当需要时）：定义tests.yaml框架模式和任何回调目录或副作用捕获要求。
VERIFY.md：描述来源+如何生成幽灵工件并针对源库验证（适配器优先；采样回退）。
- 包括上游仓库身份+精确修订（标签或提交）
- 包括用于生成每个工件的精确命令（或单个确定性再生配方）
- 包括用于运行验证和结果通过/跳过计数的精确命令
- 包括任何环境规范化假设
- 包括verification/evidence/摘要和验证器命令/结果
LICENSE*：逐字保留上游仓库的许可证文件。
- 复制常见文件如LICENSE、LICENSE.md、COPYING*
- 如果上游无许可证文件，包括一个LICENSE文件说明未找到上游许可证

6) 验证保真度（必须做）

确保tests.yaml解析且案例计数匹配或超过覆盖公共API的源测试。
确保每个操作ID至少有一个可执行（非skip）案例，除非不可行，并在VERIFY.md中列出任何例外。
优先：在源语言中创建临时适配运行器以运行tests.yaml针对上游系统（库或代理）。
- 如果源语言YAML工具弱，外部解析YAML并通过小型CLI/FFI垫片分派到库
- 断言预期结果完全匹配（功能性布局的输出/错误；协议布局的退出/状态/载荷/状态断言）
- 对于状态化工作流，执行端到端循环场景并断言跨步骤的连续性/持久化效果
- 之后删除适配器；不在幽灵仓库中交付它
- 在VERIFY.md中总结如何运行它（和结果）
在verification/evidence/中构建失败关闭证据包：
- inventory.json（公共操作+主要工作流，包括重置要求）
- traceability.csv（操作/工作流->案例ID->证据工件->适配运行ID）
- workflow_loops.json（循环案例+连续性断言+重置断言当需要）
- adapter_results.jsonl（案例级结果，带run_id、case_id、status和变异标记）
- mutation_check.json（所需变异计数+检测失败+通过/失败）
- parity.json（独立再生奇偶性判决+差异计数）
运行uv run python scripts/verify_evidence.py --bundle <ghost-repo>/verification/evidence；非零退出意味着提取不完整。
对于随机代理系统：
- 以两种模式运行场景：
  - 确定性调试模式（稳定工具输出；固定种子当可能）
  - 类似生产模式（真实采样设置）
- 运行每个关键场景N次并记录通过率+成本/延迟分布
- 发布门限：无关键不变量违反且通过率满足门限
如果完整适配不可行：
- 在所有操作ID中运行代表性样本（典型+边界+错误）
- 在VERIFY.md中清楚记录限制
使用references/verification.md获取检查清单和VERIFY.md模板。

可重现性和再生策略

幽灵仓库必须可重现：未来开发者应能指向上游修订并重新运行提取+验证。
不要添加再生脚本作为跟踪文件，除非用户明确要求；将配方放在VERIFY.md中。

输出

仅在幽灵仓库中产生这些工件：

README.md
SPEC.md
tests.yaml
TESTS_SCHEMA.md（可选；当tests.yaml有非平凡框架语义时包括）
INSTALL.md
VERIFY.md
verification/evidence/inventory.json
verification/evidence/traceability.csv
verification/evidence/workflow_loops.json
verification/evidence/adapter_results.jsonl
verification/evidence/mutation_check.json
verification/evidence/parity.json
LICENSE*（从上游复制）
.gitignore（可选，最小化）

备注

优先精确而非冗长；规则应无歧义且可测试。
保持幽灵仓库无实现代码和打包脚手架。

Zig备注

运行上游测试：优先zig build test（如果build.zig定义测试）；否则zig test path/to/file.zig用于库根和任何测试入口点。
方法的操作ID：将第一个参数名为self类型为T/*T视为实例方法（T#method）；否则使用T.method。
comptime参数：在SPEC.md中记录允许值，并在tests.yaml输入中表示为普通字段。
分配器/缓冲区：如果API接受std.mem.Allocator或调用者提供缓冲区，指定所有权和变异规则；假设分配成功，除非测试覆盖OOM。
错误：
- 功能性布局：保持tests.yaml严格（仅error: true）；在Zig适配器中，将“任何错误返回”视为通过错误案例，并依赖SPEC.md获取精确条件。
- 协议/CLI布局：优先显式机器可读错误载荷断言加退出代码。
YAML工具：Zig标准库有JSON但无YAML；对于适配器/实现，将tests.yaml转换为JSON（或JSONL）作为中间，并通过std.json让Zig运行器解析它是可以的。

资源

references/templates.md（工件大纲和YAML格式）
references/verification.md（验证检查清单+VERIFY.md模板）