让代理改动前，先读懂陌生代码仓库

让编程代理修改陌生仓库之前，先请它沿实际文件追踪一个用户操作。第一份有用的产物是证据地图：操作从哪里开始、调用哪些函数、读写什么数据，以及哪些部分仍不清楚。

仓库概览可以帮助选择从哪里入手；重要说法都能对应到文件和符号时，概览才能指导行动。GitHub 的探索代码仓库指南列出了入口、数据流、构建说明和支持证据等问题。下面把这些问题组成一次小型调查，便于交给编程代理复用。

先追踪一条应用路径

假设你接手了虚构的命令行工具 Parcel Report。第一个问题是：“用户从 JSON 文件生成报告时，程序会做什么？”它比“解释整个架构”范围更小，也给调查设定了结束点。

下面所有文件、名称和示例均为原创教学材料。本文没有执行这些片段，它们也不是从 CueSpec 或其它实际项目中提取的。

parcel-report/
  README.md
  parcel_report/
    __init__.py
    __main__.py
    io.py
    totals.py
  data/
    demo.json
  tests/
    test_totals.py

相关 README 摘录如下，保留示例文件中的原文与命令：

Run from the repository root:
python -m parcel_report data/demo.json

Suggested check:
python -m unittest discover -s tests

The CLI reads a JSON list and writes a summary to standard output.

这些是文档中的操作说明，不是命令已在你电脑上成功运行的证据。所给目录中没有打包或发布构建配置。

入口位于 parcel_report/__main__.py：

import json
import sys

from .io import load_orders
from .totals import summarize


def main():
    rows = load_orders(sys.argv[1])
    result = summarize(rows)
    print(json.dumps(result))


if __name__ == "__main__":
    main()

输入由 parcel_report/io.py 提供：

import json
from pathlib import Path


def load_orders(path):
    return json.loads(Path(path).read_text(encoding="utf-8"))

计算在 parcel_report/totals.py 中进行：

def summarize(rows):
    return {
        "orders": len(rows),
        "units": sum(row["quantity"] for row in rows),
    }

data/demo.json 中的示例输入是：

[
  {"id": "order-a", "quantity": 2},
  {"id": "order-b", "quantity": 3}
]

所给 tests/test_totals.py 包含：

import unittest
from parcel_report.totals import summarize


class SummaryTests(unittest.TestCase):
    def test_two_orders(self):
        self.assertEqual(
            summarize([{"quantity": 2}, {"quantity": 3}]),
            {"orders": 2, "units": 5},
        )

先填证据地图，再描述架构

问题	这些片段能支持的回答	文件与符号	证据边界
CLI 从哪里开始？	模块执行时调用 `main()`	`parcel_report/__main__.py` 的 main 入口判断	能看到入口路径，但没有尝试运行调用命令
路径从哪里来？	第一个命令行参数	`__main__.py`，`sys.argv[1]`	这份片段未包含缺少参数时的处理
谁读取文件？	`load_orders` 读取 UTF-8 文本并解析 JSON	`io.py`，`load_orders`	此函数没有模式校验
计算使用什么？	列表长度及每行的 `quantity`	`totals.py`，`summarize`	其它行字段不影响这次计算
程序输出什么？	将结果序列化为 JSON 并打印到标准输出	`__main__.py`，`print(json.dumps(result))`	这条路径没有出现写入输出文件的操作
展示的测试表达什么行为？	数量 2 和 3 对应 2 个订单、5 个单位	`tests/test_totals.py`，`test_two_orders`	写出的断言不是已记录的测试结果
哪里说明怎样运行检查？	提供了建议的 unittest 发现命令	`README.md`，Suggested check	命令执行情况和环境尚未验证

对应地图足够小，可以逐项查看：

CLI 参数
  -> __main__.py:main
  -> io.py:load_orders
       文件文本 -> 解析后的 JSON 值
  -> totals.py:summarize
       行记录 -> 订单数 + 数量之和
  -> __main__.py:main
       结果 -> 标准输出中的 JSON

根据手工检查，这份输入应得到 2 个订单和 5 个单位。这是从片段推导的预期，不是捕获到的终端输出。

地图也暴露了一个值得关注的边界：能解析 JSON，不等于解析结果一定是有效订单记录列表。这个发现可以用于提出后续问题，但本身不意味着应开始重写校验逻辑。

保留三个未知项

预期的数量规则未知。 示例用了正整数，但示例和测试都没有说明零、负数或小数是否合法。不要把一份样例变成业务需求。

支持的运行时和发布流程未知。 README 提供了命令，但所给文件不能确定支持哪些 Python 版本、是否有可分发的包，或怎样进行发布构建。需要时，再索取相关配置。

实际执行行为未知。 本文没有运行命令。不能因为代码看起来简单，就推断测试会通过、错误信息足够好用，或者每份检出目录里都包含相同文件。

明确未知项，有助于选择下一步。想改数量规则，就先确定规则；想处理打包，目前这些材料还不够。

复制这份只读调查请求

调查当前 Parcel Report 检出目录，不作修改。

问题：
沿文档中的 CLI 调用方式，追踪从入口到输出的路径。

先看：
README.md、parcel_report/__main__.py、parcel_report/io.py、
parcel_report/totals.py、data/demo.json、tests/test_totals.py。

返回：
1. 只包含这条执行路径的文件树。
2. 入口 -> 调用 -> 数据 -> 输出地图。
3. 含精确文件路径和符号的证据表；行号应来自实际读过的文件。
4. 文档记载的运行、检查和构建说明，并与已经验证可运行的说明分开。
5. 未知需求，以及回答它们所需的最少补充证据。

只读取源文件文本。不要安装依赖、导入项目模块、执行脚本或测试、
编辑文件或创建提交。
如果所列文件不存在，请直接说明。需要另一个源文件时，解释它回答哪个问题。
不要读取凭据或私人数据。
只描述已追踪的路径，不要声称已经理解整个仓库。

代理读不到某个文件时，相应一行仍应保留为未核实。在请求里写出文件名，不代表文件已经进入代理的上下文。

把一个已解决的问题变成改动说明

现在假设虚构维护者补充了新要求：summarize 接收的数量是整数；负整数必须引发 ValueError；零合法。这是新提供的示例信息，不是从仓库推导出的结论。

改动请求：summarize 应拒绝负整数数量。

需求来源：
本次请求附带的维护者笔记 Q-2：
范围内的输入为记录列表，各记录的 quantity 值是整数。
负数量必须引发 ValueError，零合法。

允许修改：
parcel_report/totals.py 和 tests/test_totals.py。

保持：
函数名、输入形态、输出键、正数/零的行为，以及原来的双订单示例。
不要修改 CLI、JSON 加载器、依赖、打包或类型转换策略。

在允许进行开发的环境中提出或运行这些检查：
原来的双订单案例；零数量；单独一个负数量；
其它记录合法但其中有一个负数量；空列表。

返回小范围 diff，并分清已查看的代码、手工预期、实际运行的命令、
命令结果，以及仍未确定的事项。
当前文件若与地图不同，先说明差异。

第一次调查，在能够解释选定执行路径及其未知项时结束。下一次改动请求，则从需求有出处、改动位置有边界时开始。

在 CueSpec 工作流中，需要核对回复路由时，可阅读确认目标会话。上面的证据地图是一份手工调查材料，可以用于你已有的编程工具。