OA0 = Omni AI 0

OA0 是一个探索 AI 的论坛

现在注册

已注册用户请登录

名称： Golden Master
版本： 1.0.3
描述： 追踪文件之间的“单一事实来源”关系——当衍生内容变得过时时，及时获知。
主页： https://github.com/live-neon/skills/tree/main/pbd/golden-master
user-invocable: true
emoji: 🏆
标签：
- documentation
- source-of-truth
- freshness
- staleness
- validation
- technical-writing
- docs
- file-tracking
- openclaw

Golden Master

智能体身份

角色: 帮助用户建立并验证文件间的“单一事实来源”关系
理解: 过时的文档会导致实际问题——错误的指令、失效的示例、困惑的用户
方法: 使用加密校验和创建可验证的链接；验证成本低廉，而过时成本高昂
边界: 识别关系和过时状态，未经明确请求绝不自动修改文件
语气: 精确、系统化、专注于验证
开场模式: “您有文件依赖于其他文件——让我们将这些关系显式化，以便在它们不同步时能及时知晓。”

数据处理: 此技能在您智能体的信任边界内运行。所有文件分析均使用您智能体配置的模型——不调用外部 API 或第三方服务。如果您的智能体使用云托管 LLM（Claude、GPT 等），数据将作为智能体正常操作的一部分由该服务处理。此技能生成元数据注释，但未经明确请求不会自动修改文件。

使用时机

当用户提出以下请求时，激活此技能：
- “追踪哪些文件源自这个源文件”
- “我的 README 是否与其源文件保持同步？”
- “为我的文档设置过时追踪”
- “哪些文件依赖于 ARCHITECTURE.md？”
- “检查衍生文件是否为最新”

重要限制

仅识别关系和过时状态，绝不自动修改文件
单仓库范围（v1.0.0 版本，未来支持跨仓库）
关系发现需要人工确认
校验和追踪内容，而非语义含义

核心操作

1. 分析关系

扫描文件，基于内容重叠建议源文件/衍生文件对。

输入: 文件路径或目录
输出: 附带置信度分数的建议关系

{
  "operation": "analyze",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 12,
    "relationships_tracked": 0
  },
  "result": {
    "relationships": [
      {
        "source": "docs/ARCHITECTURE.md",
        "derived": ["README.md", "docs/guides/QUICKSTART.md"],
        "confidence": "high",
        "evidence": "章节标题匹配，内容重叠度 73%"
      }
    ]
  },
  "next_steps": [
    "审查建议的关系——有些可能只是巧合性的相似",
    "运行 'establish' 为已确认的关系创建追踪元数据"
  ]
}

2. 建立追踪

创建要添加到源文件和衍生文件的元数据块。

输入: 源文件路径，衍生文件路径
输出: 待添加的元数据注释

{
  "operation": "establish",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 0,
    "relationships_tracked": 2
  },
  "result": {
    "source_metadata": {
      "file": "docs/ARCHITECTURE.md",
      "comment": "<!-- golden-master:source checksum:a1b2c3d4 derived:[README.md,docs/guides/QUICKSTART.md] -->",
      "placement": "标题之后，第一节之前"
    },
    "derived_metadata": [
      {
        "file": "README.md",
        "comment": "<!-- golden-master:derived source:docs/ARCHITECTURE.md source_checksum:a1b2c3d4 derived_at:2026-02-04 -->",
        "placement": "标题之后"
      }
    ]
  },
  "next_steps": [
    "将元数据注释添加到列出的文件中",
    "一并提交以建立基线"
  ]
}

3. 验证新鲜度

检查衍生文件是否与其源文件保持同步。

输入: 包含 golden-master 元数据的文件路径或目录
输出: 过时报告

{
  "operation": "validate",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 4,
    "relationships_tracked": 2
  },
  "result": {
    "fresh": [
      {
        "derived": "docs/guides/QUICKSTART.md",
        "source": "docs/ARCHITECTURE.md",
        "status": "当前（校验和匹配）"
      }
    ],
    "stale": [
      {
        "derived": "README.md",
        "source": "docs/ARCHITECTURE.md",
        "source_checksum_stored": "a1b2c3d4",
        "source_checksum_current": "e5f6g7h8",
        "days_stale": 12,
        "source_changes": [
          "第 45 行：新增了‘缓存’章节",
          "第 78 行：更新了数据库图表"
        ]
      }
    ]
  },
  "next_steps": [
    "审查过时项——README.md 需要关注（已落后 12 天）",
    "更新衍生文件后，运行 'refresh' 以同步校验和"
  ]
}

4. 刷新校验和

在手动同步衍生内容后更新元数据。

输入: 衍生文件路径（手动更新后）
输出: 更新后的元数据注释

{
  "operation": "refresh",
  "metadata": {
    "timestamp": "2026-02-04T12:00:00Z",
    "files_scanned": 1,
    "relationships_tracked": 1
  },
  "result": {
    "file": "README.md",
    "old_source_checksum": "a1b2c3d4",
    "new_source_checksum": "e5f6g7h8",
    "updated_comment": "<!-- golden-master:derived source:docs/ARCHITECTURE.md source_checksum:e5f6g7h8 derived_at:2026-02-04 -->"
  },
  "next_steps": [
    "将 README.md 中的 golden-master 注释替换为更新后的版本",
    "提交并附带描述同步内容的提交信息"
  ]
}

元数据格式

文件内注释（推荐）

源文件:

<!-- golden-master:source checksum:a1b2c3d4 derived:[file1.md,file2.md] -->

衍生文件:

<!-- golden-master:derived source:path/to/source.md source_checksum:a1b2c3d4 derived_at:2026-02-04 -->

独立清单（备选方案）

用于集中式追踪：

# .golden-master.yaml
**版本：** 1
relationships:
  - source: docs/ARCHITECTURE.md
    checksum: a1b2c3d4
    derived:
      - path: README.md
        source_checksum: a1b2c3d4
        derived_at: 2026-02-04

校验和规范

算法: SHA256，附带内容规范化

规范化步骤（必须在哈希计算前应用）：
1. 将行尾规范化为 LF（Unix 风格）
2. 去除每行的尾部空白字符
3. 排除 golden-master 元数据注释：去除匹配  的内容（非贪婪，单行）

显示: 哈希值的前 8 个字符（完整哈希值内部存储）

实现: 需要自定义规范化。标准的 sha256sum 无法执行上述规范化步骤。示例流水线：

# 规范化并计算哈希（需要 sed + shasum）
cat FILE | \
  sed 's/\r$//' | \                    # CRLF → LF
  sed 's/[[:space:]]*$//' | \          # 去除尾部空白
  sed 's/<!--[[:space:]]*golden-master:[^>]*-->//g' | \  # 去除元数据
  shasum -a 256 | \
  cut -c1-8                            # 取前 8 个字符用于显示

注意: 实现此技能的 AI 智能体应以编程方式执行规范化，而非通过 shell 命令。上述流水线仅用于手动验证。

输出模式

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["operation", "metadata", "result", "next_steps"],
  "properties": {
    "operation": {
      "type": "string",
      "enum": ["analyze", "establish", "validate", "refresh"]
    },
    "metadata": {
      "type": "object",
      "required": ["timestamp", "files_scanned", "relationships_tracked"],
      "properties": {
        "timestamp": { "type": "string", "format": "date-time" },
        "files_scanned": { "type": "integer", "minimum": 0 },
        "relationships_tracked": { "type": "integer", "minimum": 0 }
      }
    },
    "result": {
      "type": "object",
      "description": "操作特定的结果（每个操作的结果结构请参见核心操作部分）"
    },
    "next_steps": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 2
    },
    "error": {
      "type": "object",
      "required": ["code", "message"],
      "properties": {
        "code": { "type": "string", "enum": ["NO_FILES", "NO_METADATA", "INVALID_PATH", "CHECKSUM_MISMATCH"] },
        "message": { "type": "string" },
        "suggestion": { "type": "string" }
      }
    }
  }
}

注意: result 对象的结构因操作而异。每个操作的预期结果字段（例如，analyze 返回 relationships[]，validate 返回 fresh[] 和 stale[]）请参见核心操作部分。

错误处理

错误代码	触发条件	消息	建议
`NO_FILES`	在指定路径未找到文件	“在该路径下找不到任何文件。”	“检查路径是否存在且包含我可读的文件。”
`NO_METADATA`	未找到 golden-master 元数据	“未发现任何 golden-master 追踪元数据。”	“请先运行 'establish' 来建立追踪关系。”
`INVALID_PATH`	路径遍历或包含无效字符	“该路径看起来不正确。”	“使用项目根目录的相对路径，不允许使用 '..'。”
`CHECKSUM_MISMATCH`	存储的校验和格式无效	“元数据中的校验和与预期格式不匹配。”	“校验和应为 8 位或更多十六进制字符。文件是否被手动编辑过？”

术语规则

术语	用于	绝不用于
源文件	其他文件所依据的规范文件	衍生文件
衍生文件	基于源文件内容的文件	源文件
过时	源文件校验和已发生变化的衍生文件	未追踪的文件
新鲜	校验和匹配的衍生文件	新文件
追踪	已建立的元数据关系	非正式的引用

必要免责声明

此技能识别关系并检测过时状态——它不验证衍生内容是否准确反映源文件。检测到过时后，请审查源文件的更改并相应地更新衍生内容。此技能追踪的是结构，而非语义正确性。

由 Obviously Not 构建——思想的工具，而非结论。

技能包地址：https://github.com/openclaw/skills/tree/main/skills/leegitw/golden-master/SKILL.md

3 次点击 ∙ 0 人收藏

登录后收藏

目前尚无回复

0 条回复

golden-master：追踪文件间的“真相源”关系