让智能体在本地代码仓库中完成一次缺陷修复¶

在代码开发、数据处理和日常运维中，很多任务都依赖已经配置好的工作环境：文件保存在自己的电脑或服务器上，运行需要特定的依赖和工具，有些服务还只能通过内网访问。如果为了让智能体执行任务，必须重新上传资料、安装依赖或迁移项目，准备成本会很高，也容易出现环境不一致的问题。

MOI 的自有运行环境让你把这些已有设备接入平台，并在对话中选择它们作为任务的执行环境。智能体可以在指定工作目录中使用现有文件、依赖和命令行工具完成操作，你则可以在原来的环境中检查结果，不必为每次任务重新搭建一套环境。

下面以“修复本地 Python 项目的一个缺陷”为例，演示如何使用自有运行环境。你会准备一个带有边界条件缺陷的示例仓库，将项目目录接入 MOI，让智能体先定位问题；确认方案后，再让它修改代码、重新运行测试，最后在本地审查代码差异和修复报告。

你将完成什么¶

在电脑上准备一个可以稳定复现缺陷的本地代码仓库；
安装 astra-edge，将这个代码仓库接入为 MOI 自有运行环境；
在新对话中选择该运行环境；
让智能体运行测试、定位根因，并在修改前给出修复计划；
明确确认后，让智能体修改代码并重新运行测试；
在本地终端审查代码差异和智能体生成的修复报告。

开始前准备¶

准备一个 MOI 账号，并进入可以使用智能体和运行环境的工作区；
准备一台可以访问 MOI 服务的 macOS 或 Linux 设备。Windows 用户请在 WSL 中使用 Linux 版本；
确认设备已安装 Python 3 和 Git，并且可以在终端运行 python3 --version 和 git --version；
确认工作区中有可用的通用智能体和模型。

警告

自有运行环境会在你的设备上执行智能体请求的文件和命令操作。第一次体验请使用本教程提供的独立示例仓库，不要从主目录、系统目录或含有密钥、客户数据、生产配置的真实项目目录启动连接。

连接命令包含访问凭证，请妥善保存，并仅在准备接入的设备上运行。

本地执行不等于数据不会离开设备。智能体读取的代码、测试输出和命令结果可能会发送给模型用于推理，请遵守所在组织的代码和数据使用规则。

真正可用前需要完成什么¶

自有运行环境不是创建一个名称后就立即可用。你需要依次打通下面三层：

层次	需要做什么	如何确认
安装客户端	在目标电脑安装 `astra-edge`。同一台电脑通常只需安装一次	`astra-edge` 可以在本机运行
建立连接	进入希望交给智能体工作的目录，执行 MOI 为该环境生成的连接命令，并保持终端运行	运行环境列表显示可用，并出现已连接时长
选择环境	在新对话的运行环境选择器中选中该自有环境	发送消息前，输入区显示目标环境名称

只安装 astra-edge，设备还没有连接到 MOI；只创建环境名称但不运行连接命令，环境仍会停留在待连接状态。只有连接命令持续运行、MOI 显示环境可用，并且当前对话选中了它，智能体才会在这台设备的目标目录中执行任务。

本教程使用运行环境窗口提供的安装脚本。脚本版本由 MOI 发布目录统一管理，其他部署请使用对应环境提供的安装入口。

操作步骤¶

1. 准备一个测试失败的本地项目¶

在准备接入的电脑上打开终端，执行以下命令：

mkdir -p "$HOME/moi-runtime-tutorial"
cd "$HOME/moi-runtime-tutorial"

cat > shipping.py <<'EOF'
from decimal import Decimal

FREE_SHIPPING_THRESHOLD = Decimal("100.00")
STANDARD_SHIPPING_FEE = Decimal("12.00")


def calculate_total(subtotal: Decimal) -> Decimal:
    """Return the order total including shipping."""
    if subtotal > FREE_SHIPPING_THRESHOLD:
        return subtotal
    return subtotal + STANDARD_SHIPPING_FEE
EOF

cat > test_shipping.py <<'EOF'
import unittest
from decimal import Decimal

from shipping import calculate_total


class CalculateTotalTest(unittest.TestCase):
    def test_below_threshold_adds_shipping(self):
        self.assertEqual(calculate_total(Decimal("99.99")), Decimal("111.99"))

    def test_threshold_qualifies_for_free_shipping(self):
        self.assertEqual(calculate_total(Decimal("100.00")), Decimal("100.00"))

    def test_above_threshold_qualifies_for_free_shipping(self):
        self.assertEqual(calculate_total(Decimal("120.00")), Decimal("120.00"))


if __name__ == "__main__":
    unittest.main()
EOF

git init -q
git add shipping.py test_shipping.py

运行测试，确认问题可以稳定复现：

python3 -m unittest -v

测试结果应显示 3 个用例中有 1 个失败：订单金额刚好为 100.00 时，预期总金额仍为 100.00，实际却变成 112.00。

本地终端运行 Python 单元测试；金额恰好为免运费门槛时，预期 100.00，实际 112.00，3 个测试中有 1 个失败。

现在执行：

pwd
git status --short

确认当前目录是 moi-runtime-tutorial，并且可以看到已经加入 Git 暂存区的 shipping.py 和 test_shipping.py。暂存区将作为修改前的基线，方便稍后审查智能体产生的代码差异。

本地终端显示项目目录 moi-runtime-tutorial，以及已加入 Git 暂存区的 shipping.py 和 test_shipping.py。

运行测试后可能还会出现 ?? __pycache__/；这是 Python 自动生成的缓存目录，不要将它加入暂存区，也不影响后续审查源码差异。

本教程后续的修改和修复报告都会保存在这个目录。请保持该终端窗口可用。

完成标志：python3 -m unittest -v 稳定显示 1 个失败用例，并且当前目录是 moi-runtime-tutorial。

2. 创建自有运行环境¶

登录 MOI，进入本次教程使用的工作区。
在左侧导航进入 资源中心 → 运行环境。
找到 自有运行环境，点击 接入自有环境。
输入便于识别的环境名称，例如 本地代码修复，然后确认接入。

MOI 会打开“接入自有运行环境”窗口，其中包含本次接入专用的连接命令。当前线上页面可能只提供连接命令，不显示客户端安装入口；这种情况下按下一步独立安装即可。连接命令包含访问凭证且只显示一次，请保持窗口打开。

接入自有运行环境窗口，展示部分打码的连接命令，以及展开的安装或更新 astra-edge 区域。

如果当前账号看不到接入按钮，请先确认所在工作区是否正确，再请工作区管理员检查运行环境相关权限。

完成标志：页面显示“接入自有运行环境”窗口，并生成了连接命令。

3. 安装 `astra-edge` 客户端¶

astra-edge 是保持 MOI 与当前设备连接的客户端。同一台电脑通常只需安装一次；创建环境名称或获得连接命令并不会自动安装它。

以下命令会识别 macOS/Linux 和 CPU 架构，安装或更新 astra-edge，并保持终端的 PATH 不变，不需要管理员权限。

在准备接入的电脑上执行：

curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fsSL \
  'https://astra-suite.oss-cn-hangzhou.aliyuncs.com/bundles/2026.09.21.5/install.sh' |
  sh -s -- --no-modify-path

安装完成后检查版本：

"$HOME/.local/share/moi/client/bin/astra-edge" --version

本地终端执行安装脚本后完成客户端更新，并通过版本检查显示 astra-edge 0.2.7。

完成标志：在目标电脑执行 "$HOME/.local/share/moi/client/bin/astra-edge" --version 可以看到版本信息。此时只是安装完成，尚未连接 MOI。

4. 在项目目录连接到 MOI¶

先回到步骤 1 创建的项目目录：

cd "$HOME/moi-runtime-tutorial"
pwd

确认 pwd 指向该目录后，回到 MOI 的“接入自有运行环境”窗口，复制 连接到 MOI 下的完整连接命令，在当前终端中执行。连接命令是 MOI 为本次环境生成的，包含访问凭证；本文不提供可复用的固定连接命令。

下图仅展示连接成功的日志，图中的工作目录与本教程不同；实际操作时，请确认日志中的工作目录指向你的 moi-runtime-tutorial。

本地终端运行 MOI 连接命令，显示认证成功和 Edge agent ready 日志，以及当前工作目录。

保持该命令和终端持续运行。回到 MOI 的运行环境列表，等待 本地代码修复 显示为可用，并出现已连接时长。

智能体会以执行连接命令时的当前目录作为工作目录。如果在其他目录执行，请先停止连接，切换到正确目录后重新执行。

如果你关闭了接入窗口且没有保存连接命令，可在环境列表中点击刷新 Token 的按钮获取新命令。刷新后应使用新命令重新连接，旧命令不要继续使用。

完成标志：本地代码修复 显示为可用或已连接，运行连接命令的终端保持打开。

5. 在新对话中选择自有运行环境¶

点击左侧 新对话。
在输入区确认已选择工作区提供的通用智能体。
打开输入区的运行环境选择器。不要保留默认，在 自有运行环境 分组中选择 本地代码修复。
确认选择器显示 本地代码修复，并带有已连接状态。

只有已经就绪的环境会出现在选择器中。如果找不到刚创建的环境，请返回 资源中心 → 运行环境，检查连接命令是否仍在运行、设备是否在线，以及页面状态是否已经变为可用。

完成标志：发送消息前，输入区显示的运行环境是 本地代码修复。

6. 让智能体复现问题并定位根因¶

将以下内容粘贴到输入框并发送：

你正在排查当前本地代码仓库中的失败测试。请完成以下调查：

先运行 pwd 和 git status --short，确认当前项目和修改基线。
阅读 shipping.py 和 test_shipping.py。
运行 python3 -m unittest -v，记录失败用例、预期值和实际值。
根据代码和测试定位根因，并提出最小修复方案。
说明修复后需要重新执行哪些验证。

这一轮只调查和提出方案。不要修改任何文件，不要安装依赖，不要提交 Git 变更，也不要访问当前工作目录之外的内容。

这一次，智能体不是根据你粘贴的一小段代码猜答案，而是在你的设备上读取完整文件并执行真实测试。等待调查完成，不要关闭运行 astra-edge 的终端。

检查智能体的诊断是否包含以下证据：

当前工作目录是 moi-runtime-tutorial；
实际运行了 3 个测试，其中 test_threshold_qualifies_for_free_shipping 失败；
金额为 100.00 时，预期结果是 100.00，实际结果是 112.00；
根因是 shipping.py 使用了严格大于判断，恰好等于免运费门槛的订单没有进入免运费分支；
最小修复方案是只调整边界判断，不修改测试，也不引入新依赖。

下面是一次诊断结果示例，依次展示项目基线与失败测试、根因分析，以及修复方案和验证计划。这一轮只提出方案，尚未修改代码。

对话中已选择本地代码修复环境，智能体确认项目目录和 Git 基线，并复现 3 个测试中有 1 个失败。

智能体核对金额为 100.00 时预期 100.00、实际 112.00，定位到严格大于比较造成的边界条件错误，并提出改为大于等于。

智能体给出只修改一行判断的最小修复方案和修复后验证计划，并明确本轮尚未修改文件、安装依赖或提交 Git。

此时在本地另开一个终端，执行：

cd "$HOME/moi-runtime-tutorial"
git diff -- shipping.py test_shipping.py

命令不应输出任何差异，证明智能体遵守了“只调查、不修改”的要求。如果出现修改，先不要继续；检查差异并恢复到你确认的基线后，再开始下一步。

本地终端执行 git diff -- shipping.py test_shipping.py 后直接返回命令提示符，没有输出差异。

如果智能体提示找不到项目，先核对回复中的 pwd。路径不正确时，在本地终端停止当前连接，进入 moi-runtime-tutorial 后重新运行连接命令，再开启一个新对话重试。

完成标志：智能体给出有测试输出支撑的根因和最小修复方案，而且工作区文件尚未发生变化。

7. 确认方案并让智能体完成修复¶

确认诊断无误后，在同一对话中发送：

我已核对诊断，确认按最小方案修复。现在请：

只修改 shipping.py，不要修改 test_shipping.py。
修复金额恰好等于免运费门槛时仍收取运费的问题。
运行 python3 -m unittest -v，确认全部测试通过。
运行 git diff --check 和 git diff -- shipping.py，检查改动质量和范围。
在当前目录创建 repair-report.md，记录：失败现象、根因、实际修改、测试结果和仍需人工确认的事项。
在回复中给出修改文件、测试结果和报告的完整路径。

不要提交或推送 Git 变更，不要修改测试，不要访问当前工作目录之外的内容。

智能体现在会在自有运行环境中修改真实文件，并使用同一套本地工具链验证修改。检查结果是否满足：

3 个测试全部通过；
只有 shipping.py 的业务判断被修改；
test_shipping.py 保持不变；
git diff --check 没有报告格式错误；
当前目录生成了 repair-report.md；
智能体没有自行提交或推送代码。

下面是确认方案后的修复结果示例，展示一行代码差异、全部测试通过，以及生成的修复报告。

用户确认修复方案后，智能体将 shipping.py 中的严格大于改为大于等于，并展示 3 个测试全部通过。

智能体展示通过的测试和差异检查，以及 repair-report.md 的路径与内容摘要，并确认未修改测试、未提交或推送代码。

完成标志：智能体报告 3 个测试全部通过，并确认只修改了 shipping.py、生成了 repair-report.md。

8. 在本地审查智能体的交付结果¶

打开另一个终端窗口，执行：

cd "$HOME/moi-runtime-tutorial"
git status --short
git diff --check
git diff -- shipping.py test_shipping.py
python3 -m unittest -v
cat repair-report.md

确认满足以下条件：

git diff 中只有 shipping.py 的条件判断发生变化；
差异应当等价于把 subtotal > FREE_SHIPPING_THRESHOLD 改为 subtotal >= FREE_SHIPPING_THRESHOLD；
test_shipping.py 没有被修改；
再次运行测试仍然显示 3 个用例全部通过；
repair-report.md 中的结论与实际代码差异、测试结果一致。

下面是本地审查结果示例。首张截图顶部的 compinit / compdef 提示属于终端初始化问题，与本次修复无关。

本地终端显示 Git 状态、shipping.py 中由大于改为大于等于的一行差异、3 个测试全部通过，以及修复报告的失败现象和根因部分。

本地终端继续展示修复报告，包括实际代码修改、通过的测试、质量检查及仍需人工确认的事项。

这些修改只留在你的本地工作区中，没有被自动提交或推送。你可以继续人工审查、补充测试，再决定是否进入团队原有的代码评审流程。

完成标志：你能在本地看到最小代码差异、通过的测试和可追溯的修复报告，而且远端仓库没有发生变化。

9. 结束连接¶

本次教程完成后，回到运行 astra-edge 的终端，按 Ctrl+C 结束连接。MOI 中的环境随后会显示为未连接，也不会再出现在新对话的可用运行环境列表中。

以后需要继续使用时，进入同一工作目录，再运行该环境当前有效的连接命令。若连接凭证已经过期，或原命令已经丢失，请在 MOI 的运行环境列表中刷新 Token，并改用新生成的命令。

如果不再需要这个环境，可以在 资源中心 → 运行环境 中删除。删除环境不会自动删除电脑上的工作目录或本教程生成的文件；如需删除本地文件，请先自行确认内容。

教程完成¶

你已经把一个真实可执行的代码仓库接入为 MOI 自有运行环境，并完成了“复现失败 → 基于证据定位根因 → 人工确认 → 修改源码 → 重新运行测试 → 本地审查交付”的完整闭环。

这正是自有运行环境的核心价值：它把智能体带到工作发生的地方。智能体可以复用你已经配置好的代码、依赖、编译器、测试工具、脚本和网络条件，而结果仍然落在原来的工作目录中，供你使用熟悉的 Git 和测试流程审查。

完成本教程后，你可以把相同方法用于分析真实仓库、修复缺陷、升级依赖、执行数据脚本或排查只能从内网访问的服务。对于不依赖本地设备、希望由平台统一维护算力和网络策略的任务，则可以选择托管运行环境。

最后更新于 2026 年 10 月 15 日