智能体辅助二次开发

你可以把原本要做的 CosmoEdge 二次开发任务直接交给已经在使用的编码智能体，例如 Codex、 Claude Code 或 Copilot。推荐在一台用于开发、并与生产环境隔离的机器上打开本仓库，再通过 该智能体已有的工作区和终端权限授权它工作。无需安装 CosmoEdge 专属代理，也不用先学习提示词、 脚本参数或状态名。

最终交付代码、配置、模型产物还是部署材料，以及需要支持哪个设备，都由你的业务任务决定。 芯片参数、精度、工具链、容器、脚本和仓库实例通常是实现选择，不应成为你开始描述需求的 前置知识。仓库中的教程、实例、模板和脚本是智能体可复用的素材，不是要求所有任务得到同一种 答案。

你可以直接这样说

打开仓库并启动你熟悉的编码智能体，像向开发同事说明任务一样描述。例如：

• “我有一个训练好的人员检测模型和 20 张脱敏测试图片，希望它能在现场同型号的隔离测试设备上 运行。业务上优先少漏检，单路实时即可。模型、训练工程说明和设备型号放在我指出的目录里。 请先检查物料和开发环境，选择合适路径完成适配，交付可导入的模型、改动和验证结论；不要连接 生产设备。”
• “我的测试服务需要接收 CosmoEdge 的告警并写入现有工单系统。接口说明和测试账号已通过安全 机制提供。请复用仓库素材完成对接和本地联调，交付代码、运行说明和失败场景验证。”
• “操作人员经常填错这个配置，我希望前端能提前提示并阻止明显无效的值。请保持现有交互风格， 完成实现和构建验证。”
• “我不确定当前机器是否具备开发条件。请先只读检查；如果不满足，说明需要准备什么隔离环境， 不要直接安装或改系统配置。”

通常只需说清四件事：业务目标、手头物料、目标或测试场景、验收偏好。你不必先选择 ONNX、 BM1688、F16、某个 Docker 镜像或某个脚本。如果已知这些信息，可以作为约束补充；不知道时， 提供设备型号或不含凭据和序列号的设备信息即可。智能体负责从物料、当前仓库、实际环境和上游 官方说明中提出实现建议。找不到可靠映射时，它应如实停止在未验证层，而不是猜测。

如果工作必须在另一台隔离开发机上完成，最直接的方式就是在当前私有会话中同时告诉智能体开发机 地址、账户、密码和要做的动作，例如：“连接这台 Linux 开发机，先只读检查是否具备模型转换条件， 满足就继续；地址、账户和密码如下……”。这句话本身已经确认本任务的远程连接；如果模型也已指定， 也确认把该模型传到这台开发机。智能体不应再要求用户配置 SSH Key、别名或填写授权表。

这是有风险但受支持的开发方式：连接信息可能保留在所用智能体产品的私有会话历史中，因此只能使用 与生产隔离的开发机、临时或最小权限账户和可轮换密码。生产环境凭据不适用此入口。

你也不需要先运行仓库脚本。对模型转换、远程开发环境、模型传输或测试设备操作，仓库根目录的 AGENTS.md 会要求智能体先启用本入口；正常的本地代码、前端和文档开发命令保持不变。

智能体不应询问能自行发现的技术细节。只有下面三类缺口才值得打断你，而且应合并成一个最小问题：

• 缺少会改变交付物的业务或物料信息，例如目标设备和源模型；
• 缺少可以实际执行的隔离开发环境；
• 下一步需要新增环境变更、远程执行、模型传输或设备部署授权。

可选：给智能体更完整的工作要求

如果需要同时明确环境检查、授权和证据要求，可以复制下面的版本，再自由替换任务描述：

请先阅读仓库根目录 AGENTS.md。
任务：<用业务语言描述目标、已有物料、测试场景和期望交付物>。
我授权你在当前开发环境和仓库内做本任务所需的只读检查；写文件或安装依赖
仅限我明确授权的范围。
请先只读盘点物料和可行路径，不要让我预先选择编译器版本、容器或脚本。推荐
路径后再检查实际执行环境：满足就继续；可以补齐的，先列出变更、影响和回退；
无法满足的，告诉我应准备什么隔离环境；仓库本身做不到的，直接说明缺口。
可以开始后，从仓库选择最接近的实例、模板、脚本和代码事实并记录差异。完成后
返回交付物、实际验证证据和未验证边界。
不要把开发环境授权扩展为设备或生产环境授权，也不要索取生产凭据。

智能体会把指令整理为当前运行私有目录中的任务记录。开始执行前，它应先用一两句话复述任务和 预期交付物；你确认的是这句自然语言理解，不是 JSON 文件。随后智能体运行统一入口 scripts/agent/start.sh（Windows 为 start.ps1），安全复制你指出的物料、生成任务记录并自动完成 第一次只读路径评估。只有无法自行解决的 needsInput 才会被翻译成普通语言提问。 如果用户已经要求连接并给出了凭据，智能体会同时记录脱敏后的远程授权；地址、账户和密码不会被 复制到任务 JSON。描述中意外带入的连接信息会自动替换为脱敏标记，而不是阻断任务。

下面是智能体内部会执行的示意命令，不要求用户照抄；目标芯片未知时不传该参数，由评估继续询问：

./scripts/agent/start.sh \
  --objective "让这个检测模型在隔离测试设备上运行，并交付可复核证据" \
  --material /secure-input/person-detector.onnx \
  --target-chip bm1688 \
  --remote-linux \
  --user-requested-remote-access

运行记录位于已被 Git 忽略的 output/agent-runs/<run-id>/。该目录仍不得保存密码、Token、 私钥或带凭据的 URL；共享开发机要为不同客户使用隔离的 checkout 或工作区。

智能体如何选择路径和检查环境

统一入口会先调用 assess 只读盘点物料、当前宿主、仓库事实和授权，比较可信候选路径；任务或授权 变化后，智能体再用 scripts/agent/assess.sh（Windows 为 assess.ps1）刷新评估。上游官方教程 覆盖某条路径，只表示“可以纳入候选”， 不等于当前机器已经可用。选定路径后，再用 doctor 核对本任务真正需要的架构、资源、运行时和 可调用工具。整个只读阶段不安装软件、不拉取镜像、不启动系统服务、不修改用户组或提权。

模型转换的阶段凭据是强制串联的：当前任务的 route-assessment.json 必须为 READY，doctor 才会生成环境准入；转换和最终验证又会核对任务、评估和环境报告的哈希。修改任务或新增授权后， 旧报告自动失效，必须重跑前序阶段。高级人工命令仍可用于排障，但不能冒充这条智能体证据链。

远程连接是环境发现动作，不要求所有业务信息都先变成 READY。只要任务记录有效、用户已经明确 要求连接且评估没有判定路径不支持，智能体就可以先运行：

./scripts/agent/connect.sh \
  --contract output/agent-runs/<run-id>/task-contract.json \
  --host <开发机地址> \
  --user <开发机账户>

OpenSSH 随后在交互终端中提示密码，智能体使用用户在当前私有会话中提供的密码完成输入。密码不会 成为脚本参数，也不会写入运行记录；地址和账户可能出现在智能体产品的会话/终端历史中，但仓库只 保存脱敏后的连接结果。连接成功后先只读检查，doctor 仍需等待完整路径评估为 READY。

路径评估可能返回 READY、NEEDS_INPUT、NEEDS_ENVIRONMENT 或 UNSUPPORTED；用户无需记忆 这些状态。needsInput 只用于让智能体生成最少问题。实际执行环境检查可能返回：

脚本结论	对你的含义	下一步
READY	当前开发机满足本任务要求	冻结环境身份并继续
REPAIRABLE	可以补齐，但会改变开发环境或需要新授权	先审阅具体变更和影响，再决定是否批准
NEEDS_ENVIRONMENT	架构、资源、硬件或权限不能在当前机器安全补齐	按报告准备一台合格开发机后重试
UNSUPPORTED	当前仓库或已知工具链没有可信实现路径	记录能力缺口，不套用近似实例

这些词是脚本输出，用户不需要在任务描述中记忆或填写。没有专用检查配置的普通代码、前端或 对接任务仍可按仓库原生构建和测试命令完成；不能仅因“没有专项脚本”就判定不支持。

报告中的缺失项也不自动等于“客户机器不合格”。智能体应先核对当前仓库说明、上游官方来源和 实际命令入口，区分“开发环境确实缺少依赖”和“仓库把基础环境误写成完整工具链”。如果检查项的 owner 是 repository，应先修正文档、任务契约或脚本并重跑验证，不得让客户按错误说明安装。 例如 sophgo/tpuc_dev 只提供 TPU-MLIR 所需的基础环境，只有镜像而没有可调用的 tpu_mlir 包和转换命令时，模型转换仍不是 READY。反过来，只要当前官方路径允许、所需能力实际可调用， 就不应因为环境目录、入口布局或版本与某个示例不完全一致而阻塞；准入通过后再冻结本次实际版本、 镜像摘要、入口路径和哈希。

Windows 可以继续作为智能体、仓库检查、物料整理和任务编排入口。Sophon TPU-MLIR 转换路径的 Linux 要求来自算能开发生态，不代表 CosmoEdge 整体“不支持 Windows”。智能体应优先引导到与 生产隔离的 Linux x86_64 环境（本机、容器或远程均可按实际条件评估）；如果用户坚持 WSL 等兼容 层，应明确这是实验路径及其工具、文件系统和设备访问风险。

授权保持粗粒度

当前机制只在需要时区分四类动作：改变开发环境、远程执行、传输模型、部署测试设备。它们是风险 闸门，不是要求用户填写的固定表单。智能体应把同一阶段缺少的授权合并询问，并同时说明目标、影响 和恢复方式。工作区读写授权不会自动扩展到这四类动作，也不会从一次任务继承到另一任务。

如果用户在同一句话中提供开发机连接信息并明确要求“连接、检查或开始开发”，这已经是本任务的 remote-execution 确认；任务同时指定要上传的模型时，也包含 model-transfer。智能体通过 start 直接记录脱敏授权，不重复提问。只有用户只是贴出连接信息而没有说明动作时，才需要确认一次。

用户用自然语言确认后，由智能体记录本次粗粒度授权，例如：

./scripts/agent/authorize.sh \
  --contract output/agent-runs/<run-id>/task-contract.json \
  --grant remote-execution \
  --grant model-transfer \
  --confirmed-by-user \
  --target-reference "隔离的 Linux 开发环境"
./scripts/agent/assess.sh --contract output/agent-runs/<run-id>/task-contract.json

--confirmed-by-user 只记录已经发生的用户确认，不能让智能体自行授权。任务记录和授权建立后， 可通过 connect.sh 连接；安装依赖、拉取镜像、sudo、系统配置修改和设备部署仍需在实际需要时 说明影响并取得相应新增授权。

用户可以在当前私有任务会话中提供隔离开发机的账号和密码。智能体只能把密码输入 OpenSSH 的隐藏 交互提示，不能把它拼进命令、URL、环境变量、任务 JSON、运行证据、文档或 Git。授权记录只写 “已授予哪类动作”和脱敏后的目标引用。会话留存风险由用户通过临时账号、隔离网络和任务后轮换 密码控制。

仓库中可选择的素材

方向	当前素材	覆盖边界
模型转换	模型适配指南、ONNX 预检、转换与证据脚本、模型模板、实例索引	BM1688/F16 是首个优选的深度路径；其他芯片需要独立映射和证据
HTTP 告警联调	test/push-test-service、HTTP Webhook 参考 和相关接口代码	可用通用开发流程；首版没有同等级专项执行器和实测实例
前端二次开发	src/web/、既有组件与构建命令	按用户任务修改和构建，不套用模型流程
核心引擎	src/、构建脚本和 Catch2 测试	准备提交上游的核心改动仍遵循 Issue、评审和对应硬件证据要求

模型转换实例晋级机制目前为 Beta。是否已经完成官方晋级，以 test/agent/examples/model-conversion/index.json 中实际存在、状态为 conversion-verified、生命周期 为 active 且验收印章仍然有效的记录为准。印章短码只是证据链引用，文件中出现短码本身不证明 印章仍然有效。撤销只把生命周期改为 revoked，历史录制和印章继续保留，但该实例不得再用于 官方选择或兼容性声明。空索引只表示当前没有满足这些条件的官方实例，不妨碍普通候选按自己的 任务验收范围返回完整、部分或未验证结果。

如果交付代码在另一个项目

数据采集工具、对接服务等交付物通常属于你自己的项目。把 CosmoEdge 仓库 clone 到该项目旁边， 把两个目录都开放给智能体，并在任务开头补充：

请先阅读旁边 CosmoEdge 仓库的 AGENTS.md 和接口参考，再在我的项目里实现。
联调使用 CosmoEdge 仓库自带的 test/push-test-service，不要连接真实设备。

CosmoEdge 仓库在这种形态下提供接口契约、Mock 服务和验收事实；业务代码仍写入你的项目， 运行记录仍留在 CosmoEdge 一侧的 output/agent-runs/，避免把客户语境写进公共规范。

参考路径：让模型在测试设备上运行

例如，任务可以是“让这个人员检测模型在指定的隔离测试设备上运行，优先减少漏检，并交付可导入 产物和验证结论”。智能体应自动完成：

1. 盘点用户提供的模型、训练/导出说明、测试样本和设备信息；从可检查事实推导格式、目标映射、 输入输出和预处理，只对无法发现且影响交付的问题提问。
2. 运行 scripts/agent/start.sh，把所指物料复制到 Git 忽略的私有目录、生成任务记录并评估本机 Linux、远程 Linux 等可信路径。Windows 宿主在此阶段不报错退出为“产品不支持”。
3. 选择模型教程、模板和最接近的实例，记录为什么可复用及候选差异；实例参数不自动成为用户参数。
4. 合并询问缺少的业务、环境和授权信息。用户确认粗粒度授权后由智能体记录，并重新运行 assess； 用户不需要手写 Schema、授权 JSON 或指定工具链版本。
5. 在实际执行的 Linux 环境运行 scripts/agent/doctor.sh。它按能力发现兼容工具链，并用 compatibility-matrix 对照目标芯片、工件和仓库事实：明确冲突时报错，事实不足时标记未验证； 脚本不会自行拉镜像或安装依赖，准入后冻结实际版本、路径和哈希。
6. 运行 scripts/agent/convert_model.sh。它先执行 tools/check_onnx_model.py，再用准入时冻结的 TPU-MLIR 包、Python 和命令身份调用 model_transform 与 model_deploy；Docker 仅在任务 选择完整工具链镜像时参与，产物不写入现有模型资源目录。
7. 运行 scripts/agent/verify.sh，重新核对候选模型和产物哈希，并生成机器可读的 evidence.json 与一眼可读的 evidence.md。满足完整证据链时还会生成 seal.json 和短码； 摘要会固定说明它覆盖转换与张量对照，但不覆盖设备运行和业务精度。重跑会保留先前失败； 只有新的实测通过或明确的用户豁免可以解释其后续状态。

任务参数来自当前候选，而不是 YOLOv8n 示例的固定形状、类别数或哈希。用户明确指定其他芯片时， 不得静默改成 BM1688；没有该芯片的“编译参数 → 运行时标识 → 产物”证据时，只能完成不依赖 该映射的准备工作并标记未验证。

.pt 或 .pth 可以作为待评估物料进入统一入口，但本版本正式执行器从 ONNX 开始。训练框架导出 ONNX 是独立阶段：智能体应请求可用 ONNX，或单独评估用户的训练工程和官方导出路径；不得跳过 评估，直接安装 Ultralytics 并把一次临时导出写成已支持能力。

首个模型转换交付以 .bmodel + execution-manifest.json + evidence 为主。.bmodel 可以继续 走产品的“添加模型”配置路径，但它不等于完整导入包中的 model.nn，改扩展名也不能完成 CENN 打包。只有用户明确要求完整模型包时，才把目录、config.json、model.nn 和相应检查纳入交付。

如何理解验证结果

阶段	证明了什么	不能证明什么
ONNX 预检	模型结构可检查，ONNX Runtime 能完成零输入冒烟，输入输出已记录	检测精度
转换产物	固定工具链生成目标产物，哈希和模型信息与当前候选一致	设备能导入和持续运行
张量比对	当前工具链按用户覆盖值或该工具的默认容差策略完成转换前后输出比较，并记录所用策略	业务数据集精度
完整包检查	仅在任务要求时，包名、配置和文件契约自洽	生产兼容性
设备与业务验收	需要单独授权的测试设备、图片/视频和精度流程	不由本地通过自动升级

普通任务是否完成和是否够资格晋级为官方实例是两个结论。官方晋级缺少固定摘要或第二次录制， 不能反过来把已经满足用户要求的普通任务判失败；同样，本地任务完成也不能被表述为设备或生产 验收完成。

使用测试设备的风险

本页默认不连接真实设备，也不部署。开发机器权限不会自动扩展为设备权限。

如果你确实希望智能体操作与生产完全隔离、可恢复的测试机，可以在当前私有会话中另行说明目标、 允许只读还是允许部署、恢复方式和风险，并提供访问。 直接把测试机 IP、账号和密码交给智能体仍属于有风险的开发实验：当前产品账号可能同时拥有读写 能力，智能体宿主也可能保存会话记录。应使用临时或最小权限账号、网络隔离和可恢复数据，任务后 轮换凭据。

凭据可以出现在一次性的私有任务对话中，但不得写入可复用 Prompt 模板、任务 JSON、AGENTS.md、 教程、命令证据或 Git。生产设备、 生产凭据和不可恢复写入不属于本入口的默认支持路径。