如何在由人工智能辅助开发的代码库中让人类专家的作用得到体现

目录

1. 您将构建什么

2. 先决条件

3. 5分钟快速入门

4. 工具的工作原理

5. 如何安装“proof-of-contribution”

6. 如何搭建您的项目框架

7. 如何记录您的第一条来源信息

8. 如何使用“import-spec”来填补知识漏洞

9. 如何追踪人类的贡献来源

10. 如何通过静态分析进行验证

11. 如何启用代码审查机制

12. 下一步该做什么

您将构建什么

“proof-of-contribution”是一项基于Claude Code的工具，同时它还配备了本地命令行界面。这两者结合起来，能够帮助您……

• 来源信息块： Claude会在每一份生成的代码文件中添加一个结构化的来源说明块，列出为其提供灵感的人类开发者，并标明那些完全由人工智能生成、没有任何可追溯来源的部分。

• 知识缺口： 那些没有人类开发者参与编写、而是由人工智能生成的代码部分，在问题真正发生之前就会被发现出来。

• poc.py trace: 这是一个命令行工具，可以在30秒内显示任何文件的完整来源信息链。

• poc.py import-spec: 该工具将“贡献证明”功能与代码规范编写流程相结合，在人工智能开始生成代码之前，就能根据代码规范中的假设列表找出存在的知识缺口。

• poc.py verify: 这是一个静态分析工具，它会使用Python的AST框架来检查你的代码结构是否与预先设定的要求相符。这个工具不需要调用任何API接口；退出码为0表示代码没有问题，退出码为1则表示发现了知识缺口——该工具可以直接与持续集成系统集成使用。

• GitHub Action： 对于那些希望执行统一标准的团队来说，这是一个可选的功能：如果某个PR缺少来源信息，这个功能会自动拒绝该PR的提交。

完整的源代码可以在这里找到：github.com/dannwaneri/proof-of-contribution。

先决条件

这是一个适合初学者到中级学习者的教程。在学习之前，你应当已经掌握以下内容：

• 命令行基础操作：能够熟练地导航目录和运行脚本。

• Git：了解基本的提交和拉取请求操作。

• Python 3.8或更高版本：本工具的命令行界面完全由Python编写，不需要依赖任何第三方库。

你需要准备以下环境：

• 已安装Python：可以通过输入python --version或python3 --version来检查是否已经安装了Python。

• 已安装Git：通过输入git --version来检查是否已经安装了Git。

• Claude Code或任何支持“Agent Skills”标准的工具——Cursor和Gemini CLI也同样可以使用。

本工具不需要安装任何数据库，也不需要API密钥或付费服务。默认的存储方式是SQLite，而Python本身就已经包含了这个数据库引擎。

5分钟内快速入门

如果你想在阅读完整教程之前先试用这个工具，以下是五个命令，可以帮助你快速开始使用它并发现第一个知识缺口：

对于Mac和Linux系统：

# 1. 安装所需工具
mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git \
  ~/.claude/skills/proof-of-contribution

# 2. 设置项目结构
python ~/.claude/skills/proof-of-contribution/assets/scripts/poc_init.py

# 3> 为人工智能生成的文件记录来源信息
python poc.py add src/utils parser.py

# 4> 通过静态分析检测知识缺口
python poc.py verify src/utils parser.py

# 5> 查看完整的来源信息链
python poc.py trace src/utils parser.py

对于Windows PowerShell系统：

# 1. 安装所需工具
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/proof-of-contribution.git `
  "$HOME\.claude\skills\proof-of-contribution"

# 2. 构建项目框架
python "$HOME\.claude\skills\proof-of-contribution\assets\scripts\poc_init.py"

# 3. 记录代码的来源信息
python poc.py add src\utils\parser.py

# 4. 检查是否存在知识缺口
python poc.py verify src\utils\parser.py

# 5. 查看完整的代码来源链
python poc.py trace src\utils\parser.py

这就是整个工具的功能。下面的内容会详细说明每一步的具体操作过程，并会在每个阶段展示实际的终端输出结果。

该工具的工作原理

在安装任何工具之前，你需要先清楚地了解“proof-of-contribution”这个功能究竟是做什么的——因为其中最重要的部分其实并不那么显而易见。

“考古学问题”

以下是在每一个使用人工智能辅助开发的团队中都会出现的情景：

有一名新开发者加入团队，他们需要处理由人工智能生成的代码。在开发过程中，他们发现了一个与分页逻辑相关的错误——这个逻辑是基于光标的实现方式，而且没有人能够记得为什么当初要采用这样的设计。而最初的开发者早已离开了团队。

传统的解决方法是花费两天的时间进行“考古学式”的排查：git blame命令可以找到记录有“修复分页问题”这一操作的提交信息，但再之前的提交信息中只写着“实现分页功能”，因此排查工作陷入了僵局。

但是使用poc.py trace src/utils/paginator.py这个工具，同样的开发者只需30秒就能找到问题的根源：

代码来源追踪：src/utils/pagina.py
────────────────────────────────────────────────────────────
  [HIGH]  @tannerlinsley 在 GitHub 上
          关于光标分页机制的讨论
          https://github.com/TanStack/query/discussions/123
          见解：对于需要实时更新的数据集来说，使用光标进行分页比使用偏移量更合适

存在的知识缺口（这些内容是由人工智能生成的，并非人类编写的）：
  • 错误重试策略的实现方式——没有人类开发者提供相关说明
  • 并发写操作的处理机制——这是人工智能随意选择的

现在他们清楚地知道了这一设计模式的来源，同时也知道哪些部分是没有人类开发者参与开发的。而问题恰恰出在并发写操作的处理机制上——人工智能做出了这个选择，但却没有人对此进行过审核。

这就是这个工具的作用：它首先会进行“考古学式”的排查，而不是直接强制要求人们遵守某些规则。

知识缺口的检测机制

人们可能会认为，Claude 这个工具会自我检查并报告自己所不知道的信息。但实际上这种想法是错误的。人工智能往往会产生一些错误的认知，而一个能够可靠地检测出自身知识缺口的人工智能，是不会出现这些缺陷的。

实际上，这个工具的检测机制是基于比较而不是自我反省。

在开始开发之前，如果你使用spec-writer这个工具，它会生成一份包含明确## 需要审核的假设条件部分的规范文档——其中列出了人工智能所做的所有那些你没有明确指定的决策，以及这些决策的影响程度。这份清单其实就是你们之间的一份契约。

当你运行 `poc.py import-spec spec.md --artifact src/utils/paginator.py` 时，这些假设会被作为未解决的知识缺口存储到数据库中。在代理程序构建完成后，`poc.py trace` 命令会显示哪些假设被直接写进了代码中，而这些假设并没有引用任何人类的原始资料。

人工智能并不是在给自己出题进行考试——规范文件其实就是答案键。

poc.py verify 命令会进一步进行检查。在代理程序构建完成后，它会使用 Python 内置的 `ast` 模块解析文件的实际结构，提取出所有的函数定义、条件分支以及返回路径，然后将这些信息与数据库中存储的假设进行比对。任何没有对应匹配项的结构单元都会被认定为“知识缺口”，无论模型在编写代码时有多自信。

如何安装“贡献证明”工具

Mac 和 Linux 系统

mkdir -p ~/.claude/skills
git clone https://github.com/dannwaneri/proof-of-contribution.git \
  ~/.claude/skills/proof-of-contribution

Windows PowerShell 系统

New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
git clone https://github.com/dannwaneri/proof-of-contribution.git `
  "$HOME\.claude\skills\proof-of-contribution"

整个安装过程就是这样：不需要安装任何软件包，也不需要编辑配置文件。这个工具其实就是一个 Markdown 格式的文件，代理程序会读取这个文件；而命令行界面则是一个在本地运行的 Python 脚本。

验证安装结果：

ls ~/.claude/skills/proof-of-contribution/

你应该会看到 `SKILL.md`、`poc.py`、`assets/` 和 `references/` 这些文件。如果目录为空，说明克隆操作失败了——请检查你的网络连接，然后重新尝试。

如何为项目搭建基础结构

这个搭建脚本会在你项目的根目录下创建数据库、配置文件、命令行界面以及与 GitHub 的集成功能。每个项目都需要运行一次这个脚本。

Mac 和 Linux 系统

cd /path/to/your/project
python ~/.claude/skills/proof-of-contribution/assets/scripts/poc_init.py

Windows PowerShell 系统

cd C:\path\to\your\project
python "$HOME\.claude\skills\proof-of-contribution\assets\scripts\poc_init.py"

执行完成后，你应该会看到如下输出：

🔗 贡献证明工具初始化完成

  → 项目根目录：/path/to/your/project
  ✔ 已创建 .poc/config.json 文件
  ✔ 已创建 .poc/.gitignore 文件（数据库文件不纳入 Git 管理，配置文件会被跟踪）
  ✔ 已创建 .poc/provenance.db 文件（使用 SQLite 数据库——无需额外基础设施）
  ✔ 已创建 .github/PULL_REQUEST TEMPLATE.md 文件
  ✔ 已创建 .github/workflows/poc-check.yml 文件
  ✔ 已生成 poc.py 文件（包含 import-spec 命令）
  ✔ 已创建 .gitignore 文件

✔ ‘your-project’ 的贡献证明工具已初始化完成

这会在你的项目中生成四项内容：

your-project/
├── .poc/
│   ├── config.json      ← 项目设置（请将其提交到git）
│   ├── provenance.db    ← SQLite数据库（仅用于本地存储，git会忽略该文件）
│   └── .gitignore
├── .github/
│   ├── PULL_REQUEST TEMPLATE.md
│   └── workflows/
│       └── poc-check.yml
└── poc.py               ← 你的本地命令行工具

• .poc/ — 该工具的本地数据目录。config.json用于存储项目设置，并会被提交到git中。provenance.db是一个SQLite数据库，用于保存来源记录和知识缺口信息——仅用于本地存储，git会忽略该文件。

• poc.py — 你的本地命令行工具，被复制到了项目根目录中。可以直接运行python poc.py trace、python poc.py verify等命令，而无需进行全局安装。

• .github/PULL_REQUEST TEMPLATE.md — 一个PR模板，其中## 🤖 AI Provenance部分已经预先填好了内容。当开发者提交包含AI生成代码的PR时，需要填写这部分内容。

• .github/workflows/poc-check.yml — 一个可选的GitHub Action，用于强制执行PR相关的检查流程。该脚本会被安装到项目中，但在你没有推送相应的工作流文件并在仓库设置中启用它之前，它是处于休眠状态的。

Windows用户注意：如果构建过程中出现了UnicodeEncodeError错误，那很可能是因为PR模板中的emoji符号超出了Windows系统的编码限制。请使用文本编辑器打开assets/scripts/poc_init.py文件，找到所有以.write_text(...)结尾的行，将它们全部修改为.write_text(..., encoding="utf-8")，然后保存文件并重新运行构建过程。

验证构建脚本是否正常工作

python poc.py report

预期输出结果如下：

贡献证明报告
────────────────────────────────────────
  被追踪的成果数量：0
  具有来源信息的成果数量：0 （0%）
  未解决的知识缺口数量：0
  已解决的问题数量：0
  需要人类专家参与的部分：0

如果数据库为空，说明一切设置都已完成，你可以开始使用了。

如何记录你的第一个来源信息条目

在继续讲解之前，我想先澄清一点。之前我提到poc.py verify功能可以自动检测知识缺口，确实如此。但是这个静态分析工具只能告诉你某个函数没有人类引用的痕迹，它无法告诉你具体是哪个人或哪些资源启发了这个函数的编写。这些信息其实存在于你的脑海中，而不是代码本身。

你需要通过poc.py add命令来提供这些额外信息。在代理程序生成文件之后，你需要记录下自己实际参考过的来源资料：比如在提交请求之前阅读的GitHub讨论帖，或者对编写思路产生启发作用的Stack Overflow答案。这些记录将会成为poc.py trace显示的来源链，也会帮助poc.py verify判断哪些知识缺口已经得到解决。

verify功能用于查找知识缺口，而add功能则用于填补这些缺口。

poc.py add命令可以交互式地记录文件的相关来源信息。你可以在项目中任何由人工智能生成的文件上运行这个命令。

python poc.py add src/utils parser.py

你会看到如下提示：

正在为文件 src/utilsparser.py 记录来源信息
（按 Ctrl+C 可取消操作）

  人类编写的原始代码的 URL：（按 Enter 结束输入）：

请输入那些启发你编写这段代码的人类作者发布的原始代码的 URL。这个 URL 可以是 GitHub 上的讨论帖、Stack Overflow 上的回答、文档页面、博客文章，或者 RFC 文档。

  人类编写的原始代码的 URL：（按 Enter 结束输入）：https://github.com/TanStack/query/discussions/123
  作者名称：tannerlinsley
  平台：github/stackoverflow/docs/other
  原始代码标题：关于光标分页技术的讨论
  这段代码的编写灵感来源于哪些具体的观点？答案是：在实时更新数据集时，使用光标技术比使用偏移量技术更有效
  信任度：高/中/低 [中]：高
  ✔ 已成功记录来源信息。

根据需要添加尽可能多的来源信息。输入完所有信息后，如果没有任何来源信息，就直接按 Enter 键即可。

  人类编写的原始代码的 URL：（按 Enter 结束输入）：
✔ 来源信息已保存。运行命令：python poc.py trace src/utils parser.py

检查你记录的信息

python poc.py trace src/utilsparser.py

查看知识图谱中的所有专家
每次运行poc.py add命令时，不仅会记录原始代码的 URL，还会记录作者的信息——包括他们的用户名、使用的平台，以及他们所贡献的具体观点。如果对足够多的文件执行这个操作，这些作者的信息就会汇聚成一张知识图谱：这份图谱能够显示你的代码库是从哪些人类专家那里获得了灵感，哪些文件受到了他们的知识的影响，还有多少代码内容可以追溯到他们的贡献。
poc.py experts命令可以列出那些为代码库做出最大贡献的专家。在新的项目中，这个列表可能只有一两个条目；而在一个成熟的代码库中，这个列表就会变成一张显示哪些专家的知识对代码开发起到了关键作用的地图——如果你需要修改代码的某部分，这些专家就是你应该咨询的对象。
python poc.py experts
如何使用 import-spec 来填补知识缺口
这是该工具中最重要的命令。它将“贡献证明机制”与“规范编写工具”连接起来，从而使“知识缺口”成为可预测的因素。
在开发新功能之前使用“规范编写工具”，它会生成一个## 需要审核的假设部分——其中每一个隐含的决策都会被评定为高影响、中等影响或低影响。import-spec命令会读取这一部分内容，并将这些假设作为未解决的“知识缺口”存储到数据库中，这样在开发人员编写代码之前，这些假设就已经被记录下来了。
当开发人员完成代码编写后，任何那些在实现过程中没有被明确引用来源的假设都会自动显示在poc.py trace文件中。你不需要自己去判断代码中的哪些部分存在不确定性，因为规范文件已经告诉了你这些信息。
步骤1——创建测试规范文件
如果你还没有生成测试规范文件，可以手动创建一个，以便了解“import-spec”命令的工作原理。
Mac和Linux系统：
cat > test-spec.md << 'EOF'
## 需要审核的假设

1. 对于单名开发人员来说，SQLite足够使用——影响程度：高
   如果你需要团队共享的代码来源信息，请修改此设置。

2> 文件路径就是该文件的唯一标识符——影响程度：中等
   如果你使用内容哈希来识别文件，請修改此设置。

3> 未来的API都应该采用REST架构——影响程度：低
   如果你更喜欢GraphQL，請修改此设置。
EOF

Windows PowerShell系统：
python -c "
content = '''## 需要审核的假设

1. 对于单名开发人员来说，SQLite足够使用 - 影响程度：高
   如果你需要团队共享的代码来源信息，请修改此设置。

2> 文件路径就是该文件的唯一标识符 - 影响程度：中等
   如果你使用内容哈希来识别文件，請修改此设置。

3> 未来的API都应该采用REST架构 - 影响程度：低
   如果你更喜欢GraphQL，請修改此设置。
'''
open('test-spec.md', 'w', encoding='utf-8').write(content)
print('test-spec.md已创建')
"

注意：不要使用PowerShell的echo命令来创建测试规范文件。PowerShell会将文件保存为UTF-16格式，而当import-spec命令读取这些文件时，就会引发UnicodeDecodeError错误。上面使用的python -c方法能够正确地生成UTF-8格式的文件。
步骤2——导入假设信息
python poc.py import-spec test-spec.md --artifact src/utils/parser.py

规范文件中的假设信息已成功导入——共生成了3个“知识缺口”
───────────────────────────────────────────────────────
  1. [高影响] 对于单名开发人员来说，SQLite足够使用
       如果你需要团队共享的代码来源信息，请修改此设置。

  2. [中等影响] 文件路径就是该文件的唯一标识符
       如果你使用内容哈希来识别文件，請修改此设置。

  3. [低影响] 未来的API都应该采用REST架构
       如果你更喜欢GraphQL，請修改此设置。

  → 这些假设信息将与src/utils parser.py文件相关联。
  在开发人员完成代码编写后，请运行以下命令：
  python poc.py trace src/utilsparser.py
  python poc.py add src/utilsparser.py

步骤3——追踪知识缺口
python poc.py trace src/utils parser.py
知识缺口（由人工智能生成，无人类来源）：
  • 未来任何API应采用REST架构 [如您偏好GraphQL，请修改此选项]
  • 对于单开发者使用而言，SQLite已经足够 [如需要团队共享的代码来源信息，请修改此选项]
  • 文件路径被用作文件的标识符 [如您使用内容哈希来识别文件，请修改此选项]

  解决这些缺口：python poc.py add src/utils parser.py
共有三个知识缺口，它们根据紧急程度被用不同颜色标示出来。那些影响较大的缺口会以红色显示，而影响较小的则用绿色显示。当您运行poc.py add并为某个缺口提供了相应的人类来源信息时，该缺口就会自动被填补。
不进行编写即可预览
python poc.py import-spec test-spec.md --dry-run
这个命令会解析规格文件，并显示在不修改数据库的情况下应该添加哪些内容。在正式决定导入这些内容之前，使用这个功能非常有用。
检查整体运行状况
python poc.py report
如何追踪人类作者的信息
poc.py trace这个命令是您会最常使用的。它能够显示任何文件的完整编写者信息链，并列出所有知识缺口——也就是那些没有可追溯的人类来源的代码部分。
python poc.py trace src/utils parser.py
一个同时包含编写者信息和缺口信息的文件示例如下：
填补知识空白
对于那些存在未引用代码的文件，运行 poc.py add 命令即可：
python poc.py add src/utils/parser.py

当你输入某个与未引用代码相关的信息时，这些空白会自动被填补。再次运行 poc.py trace 命令，就可以确认问题已经得到解决。
如何通过静态分析进行验证
poc.py verify 这个命令能够彻底消除认知上的空白。它通过分析文件的实际代码结构来检测知识空白，而不是让人工智能去说明自己不知道什么。
在代理程序构建完成后，并且你已经使用 import-spec 命令添加了需要验证的代码片段之后，再运行这个命令：
python poc.py verify src/utils parser.py

预期的输出结果如下：
验证结果：src/utils/parser.py
────────────────────────────────────────────────────────────
  检测到的代码结构单元数量：11个
  已添加的待验证代码片段数量：3个
  其中已有引用来源的代码片段数量：2个
  存在明确未引用来源的知识空白数量：1个

明确存在的知识空白（没有人类可参考的来源）：
  • 函数：handle_concurrent_writes（位于第47至61行）
      原先添加的待验证代码片段：关于并发写操作的处理机制——人工智能是随意选择了这个函数进行检测的

  解决方法：运行 python poc.py add src/utils parser.py

上面显示的知识空白并不是Claude承认存在的，而是分析工具通过比较文件中的函数列表与你预先添加的待验证代码片段后发现的。函数 handle_concurrent_writes 确实存在于代码中，但数据库中并没有找到任何相关的引用来源，因此才被标记为知识空白。
退出码的含义
python poc.py verify src/utils parser.py
echo $?   # 在Mac/Linux系统中使用
python poc.py verify src/utils parser.py
echo $LASTEXITCODE   # 在Windows PowerShell系统中使用



退出码0 — 没有发现任何知识空白，所有检测到的代码结构单元都有相应的引用来源


退出码1 — 发现了知识空白，需要使用 poc.py add 命令来填补这些空白


退出码2 — 文件未找到，或者使用的编程语言不被支持


退出码1可以直接集成到持续集成流程中。你可以在GitHub Action或预提交钩子中添加 poc.py verify 命令，这样在构建过程开始之前，系统就能检测到存在的知识空白并阻止构建继续进行。
不使用预先添加的代码片段进行验证
如果你还没有先运行 import-spec 命令，verify 命令仍然可以正常使用——它会自动切换到静态分析模式，并将所有没有引用来源的函数或代码片段都标记为知识空白：
python poc.py verify src/utils parser.py

预期的输出结果如下：
⚠ 未导入任何参考规范——因此会显示所有没有引用来源的代码结构单元。
  建议先运行：python poc.py import-spec spec.md --artifact src/utils parser.py
  以便进行明确的知识空白检测。

明确存在的知识空白（没有人类可参考的来源）：
  • 函数：parse_query（位于第1至7行）
  • 分支：if not text（位于第2至3行）
  • 函数：fetch_results（位于第9至12行）
  ...

这种方法不如使用“规范编写工具”来得精确——因为它会显示所有结构单元，而不仅仅是那些与特定假设相关的单元——但无论是对于新文件还是旧文件来说，它都可以作为一种基准参考。
`–strict`标志
python poc.py verify src/utils parser.py --strict
严格模式会将所有未被引用的结构单元标记为“缺失项”，即使某些声明已经被明确提及也是如此。当你要求零容忍时，就可以使用这种模式：任何没有人类来源信息的函数或代码分支都会通过检查失败。
如何启用PR检查功能
只有当`poc.py trace`真正为你节省了大量时间之后，才去启用GitHub Action这个功能。这个顺序很重要——如果在团队刚开始使用该工具时就启用它，人们可能会认为这是一种额外的负担；而等到团队已经从中获得了实际收益后再启用它，就会让它成为一种标准流程。
git add .github/ .poc/config.json poc.py
git commit -m "chore: add proof-of-contribution"
git push
之后，所有的PR提交都会被检查是否包含`## 🤖 AI Provenance`这一部分。系统已经预先创建好了包含该部分的PR模板，开发者们在本地运行`poc.py trace`后，只需按照模板要求填写相关信息即可。
那些编写完全由人类编写的代码的开发者，可以在PR文本中添加“100% human-written”这样的说明，这样系统就会自动跳过对该部分的检查。
该功能会检查什么
这个工具会读取PR提交的描述，并检查以下内容：


`## 🤖 AI Provenance`这一标题


归属信息表中是否至少有一行内容被填写


如果缺少这个部分或者表格为空，系统就会检查失败，并会留下评论提示开发者需要添加哪些信息。评论中还会提供链接，指向`poc.py trace `，这样开发者就能知道应该去哪里查找相关资料。
下一步该怎么做
在实际功能开发中结合使用规范编写工具
`import-spec`这个工具的真正价值在于实际的功能开发过程中，而不是在测试规范的编写上。如果你使用了spec-writer，那么具体的工作流程如下：
/spec-writer "你的功能描述"
将生成的输出文件保存到`spec.md`中。然后执行以下命令：
python poc.py import-spec spec.md --artifact src/path/to/output.py
使用你的开发工具构建这个功能，然后再运行`poc.py trace`来查看哪些假设被直接写进了代码中，而这些假设其实并没有人类来源信息。优先解决那些影响较大的问题——因为这些问题很可能会导致生产环境出现故障。
激活Claude代码生成功能
当`SKILL.md`文件被启用后，Claude会在生成的每个文件中自动添加一个“来源信息块”。这个块会列出Claude所参考的人类来源资料，并标明哪些内容是Claude自行合成的、没有可追溯的原始来源的信息。
要在Claude Code中激活这一功能，该技能已经安装在~/.claude/skills/proof-of-contribution/路径下。当你处于包含.poc/config.json文件的项目中时，Claude Code会自动加载该技能。
生成的原产地信息块如下所示：
## 贡献证明
生成的成果：fetch_github_discussions()
置信度：中等

## 对此产生启发的人类资源

[1] GitHub GraphQL API文档团队
    来源类型：官方文档
    URL：docs.github.com/engraphql
    贡献内容：基于游标的分页机制

[2] GitHub社区（多位贡献者）
    来源类型：GitHub Discussions
    URL：github.com/community/community
    贡献内容：针对被删除账户的“ghost”备用方案
                  该方案在错误报告中被提及

## 知识缺口（由AI生成，未引用任何人类资源）
- 错误处理/重试逻辑
- 速率限制策略

## 建议咨询的人类专家
- 关于分页机制，可咨询github.com/octokit社区
“知识缺口”这一部分是其他工具所没有的。在这一部分中，AI会承认自己生成的内容并未来源于任何可追溯的人类资源——这样就可以避免这些知识缺口在实际生产环境中引发问题。
当你的需求超出SQLite的能力范围时，就该进行升级了
默认使用的数据库是SQLite——它仅用于本地使用，不需要任何基础设施。当你需要团队协作或执行图谱查询时，仓库中的references/目录中提供了相应的迁移指南：



需求
相关文件




团队共享原产地信息数据库
references/relational-schema.md


图谱遍历查询
references/neo4j-implementation.md


语义网/互操作性相关内容
references/jsonld-schema.md



手动跟踪与贡献证明机制的对比




手动跟踪
贡献证明机制




确定代码的编写者

在Slack中搜索，向团队询问，或仔细查看代码提交记录
使用poc.py trace 命令——耗时约30秒


了解哪些部分是AI推测出来的
在代码正式投入使用之前，你无从知晓这些信息
通过“知识缺口”部分，在代码发布前就能发现问题


在构建完成后检测知识缺口
需要通过代码审查才能发现这些问题
使用poc.py verify命令进行静态分析，无需调用任何API接口


强制要求在Pull Request中注明代码来源
依赖道德准则来确保这一点
如果缺少来源说明，GitHub Action会拒绝该Pull Request


将假设内容与规范文档关联起来
需要手动将假设信息复制到评论中
使用poc.py import-spec命令，这些假设信息会自动被标记为已跟踪的内容


所需基础设施
无需任何基础设施（通常只需要电子表格即可)
完全不需要额外基础设施——仅使用SQLite和纯Python代码，无需支付任何服务费用



这个工具并不能替代代码审查。它只是为代码审查提供了必要的背景信息，从而帮助审查人员发现其中存在的问题。
在那种需要花费两天时间、通过那些毫无意义的提交信息来追踪错误的场景中，使用poc.py trace只需要三十秒钟就能完成同样的工作。虽然代码中仍然存在一些缺陷，但至少现在你知道这些缺陷具体位于哪里了。
该工具由 Daniel Nwaneri开发而成。import-spec所依赖的规范编写工具的代码托管在github.com/dannwaneri/spec-writer上。而所有与该项目开发相关的代码都保存在github.com/dannwaneri/proof-of-contribution这个仓库中。