TAX编译智能体使用指南（Web工作台）
文档说明
本手册面向使用 Web 工作台完成「模型 → NPU 适配与验证」任务的用户，说明从选择任务、生成任务契约、提交执行，到跟踪 Agent 执行流、查看阶段性成果、回看历史案例的完整操作路径。
手册不涉及平台后台的调度、门禁（Gate）与证据（Evidence）实现细节；相关概念只在解释界面现象时简要引用。
本手册依据产 Web 工作台实际界面编写。界面字段与选项随版本迭代可能调整，以页面实际展示为准。
产品简介
平台能做什么
平台以智能体为核心，把模型编译的各个环节——图切分、算子映射、内存规划、指令生成——标准化为多个专家智能体，自动完成大模型在定制 NPU 上的适配、构建、真机验证、服务验证、性能调优与知识回流；出现编译失败、数值分叉或性能瓶颈时，可自动定位首错、生成可证伪假设与修复候选，并执行最小实验后重规划。
基本概念
| 概念 | 含义 | 在界面上的体现 |
|---|---|---|
| 任务契约 | 一份结构化任务书，锁定「适配什么、在哪里做、怎样算完成」以及授权范围 | 「生成任务契约」弹窗 + 填入输入框的契约正文 |
| Agent 执行流 | 智能体的回复、工具调用、命令输出与实测结果的完整记录 | 左下面板「Agent 执行流」 |
| 阶段（S0–S12） | 从环境准入到知识回流的可恢复生命周期，每阶段有独立目标与门禁 | 「阶段性成果」中按 S1/S2/S3… 排列的卡片 |
| 门禁（Gate） | 决定「能否进入下一阶段」的确定性判定，只认证据，不认自评 | 阶段卡片上的「已通过」等结论 |
| 成果与证据 | 适配产物、验收结论、每次迭代的证据文件 | 「阶段性成果」面板、「全部文件」与文件查看弹窗 |
关键原则：验收结论只取自实际 Run 与 Gate。文件生成、进程退出、HTTP 200 都不等于验证通过。界面底部对此有常驻提示。
界面总览
进入任务后，页面自上而下分为以下区域：
-
顶部导航栏：产品标识「希姆计算」「RISC-V 编译智能体实践」、「任务列表」入口、右侧「执行环境」（含执行环境 ID）、「退出课堂」与用户菜单。
-
任务标题区：当前任务名称（如「任务1: HunyuanOCR 单卡适配」）、状态标签（如「未提交」「本轮已结束」）、一行任务说明；历史任务还会显示运行标识（如 history-hyunyuanocr-20260918）与右上角「切换任务」。
-
任务输入区：契约正文输入框 + 工具条（「生成任务契约」按钮、操作链提示、字符计数）+ 右侧主操作按钮（「预览并提交」或「补充预算并继续」）。右上角常驻一行授权说明，例如「选择实验选项，完整预览契约后确认执行」「追加指令保留原契约与授权范围」。
-
主体两栏：
-
左栏「Agent 执行流」：智能体执行过程，底部有「跟随新消息」与「后台执行与页面连接独立」提示。
-
右栏「阶段性成果」：阶段验收结论、成果与证据入口，右上角「全部文件」。
-
-
页面底部：固定展示「希姆计算 · 提供技术与实践环境」与「真实执行 · 证据验收 / 关于本实践」，可作为对平台性质（真实执行、以证据验收）的确认。
快速开始
提交一个适配任务的整体路径：任务列表选择任务 → 生成任务契约 → 填入并补充编辑 → 预览并提交。
第一步：选择任务入口
点击顶部「任务列表」，弹出任务列表面板。面板提供两个入口，切换查看不会停止后台执行：
| 入口 | 用途 | 状态标签 |
|---|---|---|
| 任务 1：HunyuanOCR 单卡适配 | 选择实验选项，复制独立工程并完成真机 OCR 适配与验证 | 待启动 / 未提交 |
| 任务 2：回看历史案例 | 查看历史运行、阶段成果与验收依据 | 历史案例 / 本轮已结束 |
-
首次实践选「任务 1」，从零开始一次真实适配。
-
想先看懂平台产出长什么样、或复核已有结论，选「任务 2」。
-
面板底部的横向滚动条说明列表可横向拖动查看更宽的说明列。
第二步：生成任务契约
在「任务输入」区点击左下角的「生成任务契约」，弹出三步式配置弹窗。
弹窗分为左侧配置区与右侧「实验概要」，配置区按三个问题组织：
① 适配什么
| 字段 | 必填 | 说明 |
|---|---|---|
| 实验任务 | 是 | 决定契约模板与阶段序列，例如「HunyuanOCR 单卡适配」 |
| 模型 | 是 | 待适配模型，例如 HunyuanOCR |
| 模型来源 | 是 | 权重与配置的来源版本，用于资产登记与血缘追溯 |
| 参考实现 | 是 | 数值对拍用的参考实现（例如 CPU 参考结果） |
② 在哪里做
| 字段 | 必填 | 说明 |
|---|---|---|
| 目标芯片 | 是 | 例如「STCP950 · 系统分配物理卡」；具体分配的物理卡与任务目录在最终预览中展示 |
| 工程起点 | 是 | 例如「stc_llm + stc_llm_dnn 独立副本」，表示复制独立工程，不污染主仓 |
| 编程智能体版本选择 | 是 | 执行本任务的智能体与工具版本组合 |
| 运行环境 | 是 | 目标 Host/NPU 测试环境 |
③ 怎样算完成
| 字段 | 必填 | 说明 |
|---|---|---|
| 交付档位 | 是 | 验收深度与预算档次，例如 smoke（快速验证档） |
| 执行阶段 | 是 | 本次执行推进到哪个阶段为止 |
| 验证要求 | 是 | 例如「真机 OCR，与 CPU 参考结果比较」 |
| 执行预算 | 是 | 本次执行可消耗的算力/时间预算 |
| 补充说明 | 否 | 可留空；不能取消真机验证，也不能扩大设备授权 |
操作要点：
-
右侧「实验概要」实时汇总你的选择，未选的项显示「待选择」，提交前用它做最后核对。
-
摘要是只读的，修改必须回到左侧对应下拉框重新选择。
-
弹窗左下角提示：「点击『填入任务输入框』只生成契约；最终预览后确认提交才会建立任务并执行。」——即生成本身不消耗资源，也不需要设备。
-
点击「取消」或右上角「×」放弃本次配置，已填选项不保留。
第三步：填入输入框并补充编辑
点击「填入任务输入框」，弹窗关闭，契约正文写入输入框。
此时界面变化：
-
输入框内出现契约正文（以 # 开头的标题行 + 任务要求），例如「使用 Agent X 完成 HunyuanOCR 单卡适配。必须实际执行适配、构建、真机推理和结果验证，不要只给出方案。」
-
按钮下方的操作链提示由「选择实验选项 → 填入契约 → 预览并提交」变为「契约已生成 · 如需修改请重新选择选项」。
-
字符计数由 0/60000 变为实际字数（如图中 2241/60000），上限 60000 字符。
-
右侧「预览并提交」由灰色不可用变为可点击。
补充编辑的边界：你可以直接在下拉框外的正文里增补要求（补充验收口径、指定输入样本、说明已知限制等），这属于对任务要求的细化。但选项类内容（模型、芯片、工程起点、交付档位、预算、授权范围）不会被文本框编辑改变——要改这些，必须重新点击「生成任务契约」重新选择，契约会整体替换。这是平台「选项即授权」的设计，避免用一句文字绕过设备与权限边界。
第四步：预览并提交
点击「预览并提交」，进入最终预览：确认冻结的选项、物理卡与任务目录、将建立的执行阶段，然后确认提交。提交后：
-
任务状态由「未提交」转为执行态，任务标题区的状态标签随之更新。
-
「Agent 执行流」从空态「等待任务提交」开始滚出消息。
-
「阶段性成果」从提示「提交任务后，查看阶段成果」开始出现阶段卡片。
提交前请自检：模型与模型来源是否指对版本、目标芯片与运行环境是否为目标机器、交付档位是否匹配你想要的验收深度、执行预算是否够走到目标阶段。契约提交后由 Controller 冻结为同一 Plan revision，中途改档位会失效已产生的证据。
观察 Agent 执行流
主会话与子会话
「Agent 执行流」右上角的下拉框用于切换会话：
-
主会话 · 共 N 条消息：汇总本次运行的全部对话与工具调用，默认视图。
-
agent-0 ～ agent-11 · 共 N 条消息：各专家智能体的独立会话，括号中的条数是该会话的消息数量。
使用建议：想整体了解「做了什么、结论是什么」，看主会话；想追某个具体问题（例如某个阻塞是怎么被排除的），按条数异常偏多的子会话切入，那里通常集中了该智能体的主要推理与实验。
消息阅读与操作
-
消息内容包含智能体回复、工具调用与命令、实测输出（代码块形式呈现）、以及「附注」式的结论说明。
-
底部「跟随新消息」勾选时，视图自动滚动到最新消息；阅读历史时取消勾选，避免被打断。
-
长会话左下角显示「保持末尾位置」「94/1202 条消息」与「加载更早记录」，用于分批加载更早的消息，避免一次渲染过多内容。
-
右下角常驻提示「后台执行与页面连接独立」：关闭页面、刷新或切换任务不会中断后台执行；重新进入任务后可继续查看，执行流按消息 ID 续接。
查看阶段性成果
右栏「阶段性成果」是本次运行的验收视图，也是你判断「做到哪一步、能不能继续」的主要依据。
面板头部：先看结论，再看细节
自上而下依次为：
-
总体状态：如「执行已结束 · 交付未通过」，紧接一行「部分成果可用」——说明虽然最终交付门禁未通过，已完成阶段的产物仍可作为后续工作基础。
-
未闭环项高亮条：如「S9: VS-ORACLE 部分满足: ie_parallel 稳定缺字段并在服务路径下重复输出」，直接指出卡在哪个阶段、哪项验收口径、现象是什么。
-
交付口径：「交付目标: smoke · 当前计划 r5」，用于核对本轮的交付档位与计划版本号（r5 表示计划已修订到第 5 版）。
「当前成果」页签
按阶段顺序展示阶段卡片，每张卡片包含：
-
阶段名与编号：如「模型分析与适配计划 / S1」「模型资产与权重映射 / S2」，右侧为结论标签（如「已通过」）。
-
一段摘要：说明该阶段实际做了什么、关键值是什么（例如「S1 候选在冻结 revision 下重出，sha256 与原报告一致」）。
-
三个入口：
-
查看成果：打开该阶段的核心产物文件；
-
验收依据：打开支撑该结论的证据（Comparison、报告、快照等）；
-
历史记录：查看该阶段的历次尝试与修订。
-
「展开成果与证据」：展开后列出该阶段全部产物与证据条目，可直接下钻到文件。
-
「未解决问题 · N 项」：折叠区，列出该阶段遗留的未决项（缺口、风险、待补证据），是申请人工协助或追加预算前必看的内容。
「迭代历史」页签
点击「迭代历史」切换到时间线视图：
-
顶部「阶段」下拉可按阶段过滤：全部阶段、S1、S2、S3、S4、S5、S9、S12（选项随本次运行实际涉及的阶段变化）。
-
右侧注明排序规则「按记录时间排列 · 北京时间」，时间线自上而下由新到旧。
-
每条记录包含阶段编号、阶段名、动作摘要与执行状态，例如「S1 模型分析与适配计划 / 执行已完成」「S3 … / 执行已完成」「S9 执行任务 / 计划 r5」。
-
迭代历史是不可覆盖的：每次重试或重规划都会新增记录，历史记录只增不改，因此可以用它回溯「同一问题试过哪几种假设」。
全部文件
右栏右上角「全部文件」打开本次运行的文件清单，按目录结构组织（如 archive/evidence/S3-snapshot/…、docs/…、scripts/…）。此入口用于「按文件找人」——例如想知道某份报告是否已写入工程、某次迭代是否留下了快照。
查看成果文件
在「查看成果」「验收依据」「展开成果与证据」或「全部文件」中点击任一文件，打开文件查看弹窗：
| 区域 | 元素 | 说明 |
|---|---|---|
| 标题 | 文件路径 | 完整相对路径，如 archive/evidence/S3-snapshot/S3-host-oracle.md |
| 副标题 | 来源与指纹 | 如 history_real · sha256:358a8ff5…，用于确认这份证据的来源与内容未被篡改 |
| 左上 | 返回文件列表 / 重新读取 | 返回上级清单；文件被后台重新生成后，用「重新读取」拉取最新内容 |
| 右上 | 文件版本 | 下拉选择历史版本，如 v1 · 2026/10/22 16:20:44；同一文件的多版可逐版对比 |
| 右上 | 下载原文件 | 下载未经渲染的原始文件（Markdown、JSON、日志等） |
| 右上 | × | 关闭弹窗，不影响后台执行 |
| 正文 | 渲染结果 | Markdown 以排版形式呈现，表格、代码块、结论摘要可读 |
阅读建议：先看文件头部的来源信息（Run、角色、生成日期、输入 revision），再看结论摘要表。例如 S3 Host Oracle 报告会明确写出「真实图像 → 真实 greedy 解码 = 跑通（非 mock）」「与官方 README 真值对拍 ie_parallel.jpg，8/8 字段逐字一致」这类可核对结论，以及「文本输出后处理（tail-repeat / markdown 规整）故意不做」这类显式限制。凡标注「故意不做」「未宣称」的项，不应在汇报中当作已达标。
回看历史案例并继续推进
历史案例用于复核已有运行的完整链路，或在原契约范围内追加指令继续执行。
进入历史案例
两种方式：
-
顶部「任务列表」→「任务 2：回看历史案例」；
-
在任务页右上角点击「切换任务」。
进入后标题区显示「任务2: 回看历史案例」、状态「本轮已结束」和运行标识 history-hyunyuanocr-20260918。
选择历史运行身份
「任务输入」区第一行是「历史运行身份」下拉，列出可复核的运行，例如 hunyuanocr-single-npu2-ds41v2-20260918。切换运行身份后，执行流与阶段性成果同步切换为该次运行的内容。要复核不同芯片配置或不同轮次的结果，在这里切换，不要新建任务。
追加指令与追加预算
| 元素 | 行为 |
|---|---|
| 输入框（占位文字「补充要求，或输入下一步指令」） | 填写对本次历史运行的补充要求，上限 8000 字符（0/8000） |
| 「生成任务契约」按钮 | 灰色不可用，旁注「新指令不覆盖已提交契约」——历史案例的契约已冻结，不能用新配置替换 |
| 「补充预算并继续」 | 提交补充指令并为继续执行追加预算，主操作按钮在输入有效后可用 |
| 右上提示 | 「追加指令保留原契约与授权范围」 |
规则理解：在历史案例里，你只能「在原有契约与授权范围内追加要求」，不能借补充指令更换模型、芯片、工程起点或扩大设备授权。需要换配置时，回到任务列表走任务 1 的契约流程新建任务。既有历史记录不会被覆盖，继续执行会以新的计划版本推进。
复核一份「未通过」的运行
以截图中这轮为例，值得学习的复核顺序：
-
看头部结论：「执行已结束 · 交付未通过」「部分成果可用」。
-
看待闭环项：S9 的 VS-ORACLE 部分满足，现象是 ie_parallel 稳定缺字段并在服务路径下重复输出——即问题定位在服务/协议层的字段完整性，而非底层数值。
-
看「当前成果」中已通过的阶段：S1、S2 均「已通过」，说明模型指纹与权重映射可信，可作为后续工作的基线。
-
用「验收依据」核对结论，必要时下载原文件；用「历史记录」看该阶段试过什么。
-
结论表述要区分层级：能说「S1/S2 已通过、S9 部分满足、整体交付未通过」，不能说「验证基本完成」。
状态与结论说明
任务状态
| 界面标签 | 含义 | 你的下一步 |
|---|---|---|
| 未提交 | 契约尚未填入或尚未预览提交 | 生成契约 → 填入 → 预览并提交 |
| 待启动 | 任务已建立，等待调度与资源 | 等待执行流出现消息；可离开页面 |
| 执行中 | Agent 正在执行 | 观察执行流与阶段成果，无需干预 |
| 执行已结束 · 交付通过 | 目标阶段的强制门禁全部通过 | 按需下载产物与证据归档 |
| 执行已结束 · 交付未通过 | 有阶段未闭环，但已完成阶段成果可用 | 查看未闭环项与「未解决问题」，补预算继续或转人工 |
| 本轮已结束（历史） | 历史运行的终态 | 复核成果与证据；如需推进走「补充预算并继续」 |
| 历史案例 | 历史运行的查看入口 | 仅用于查看与追加指令 |
阶段结论
阶段结论对应产品需求中的门禁判定等级，界面上以标签与颜色区分：
| 结论 | 含义 | 处理建议 |
|---|---|---|
| 已通过 | 该阶段强制条件全部满足，可进入下一阶段 | 无需处理 |
| 部分满足 | 部分验收口径未达标，但已有可复用产物 | 查看「未解决问题」，判断是否补预算或转人工 |
| 未通过 / 阻塞 | 存在正确性失败或关键证据、环境、资源缺失 | 先解决阻塞项，再触发重验 |
| 待补充证据 | 结论缺少必要证据支撑 | 不得据此推进，也不得在汇报中引用为通过 |
任何阶段结论都绑定当次的版本、运行与设备状态。模型、权重、源码、工具链、软件栈、拓扑或输入变化后，旧结论会自动失效并触发最小重验，界面上会体现为新的迭代记录。
常见问题
为什么「预览并提交」一直是灰的？
契约还没填入输入框。必须点击「生成任务契约」→ 选完选项 → 点「填入任务输入框」，按钮才会启用。直接在文本框里手写内容不会启用提交。
契约填入后想改「目标芯片」，直接改文字行不行？
不行。文本框编辑只改变任务要求的表述，不改变已登记的选项与授权范围。请重新点击「生成任务契约」重新选择，契约会整体替换，然后重新预览。
关掉页面或切换任务，任务会不会中断？
不会。执行流底部明确提示「后台执行与页面连接独立」。切回任务后执行流会继续更新，更早的消息用「加载更早记录」补齐。
为什么执行结束了却显示「交付未通过」？
门禁逐阶段判定，任一强制条件不满足即不得推进。「交付未通过」说明目标阶段未全部闭环，不代表所有工作白做——「部分成果可用」与已通过阶段仍可作为后续基线。
文件都生成了，为什么不能算通过？
验收结论只取自实际 Run 与 Gate。文件存在只代表有产物，不代表数值、协议、资源或设备健康达标。界面底部对此有常驻提示。
补充说明里能不能写「跳过真机验证，直接给方案」？
不能。补充说明可以细化要求，但不能取消真机验证，也不能扩大设备授权范围。此类指令不会被采纳。
历史案例为什么不能改契约？
历史案例的契约与授权范围已冻结，用于保证复核可重算。界面标注「新指令不覆盖已提交契约」，只能追加要求并用「补充预算并继续」推进。
遇到需要人工决策的地方怎么处理？
平台只在策略要求审批、外部条件阻塞、缺少安全工具、诊断不收敛或设备无法安全恢复时请求人工协助。此时会给出冻结版本、首错、已尝试任务与候选假设、最小复现与证据、建议岗位与恢复条件；你只需针对被问的那一项给出决定或补充资料。
执行环境 ID 有什么用？
顶部「执行环境」旁显示的环境 ID（如 7de29fa4e）标识本次实践使用的环境实例。反馈问题或申请资源时提供该 ID，便于定位。
可以提交敏感数据吗？
不可以。密钥、生产凭据、受限数据不得写入契约、补充说明或任何输入字段；平台上所有输入都会进入任务记录与证据链，按项目授权范围可见。
附录A：阶段速查（S0–S12）
界面上「阶段性成果」的阶段编号对应如下职责与主要产物，便于把卡片与文档术语对应起来：
| 阶段 | 职责 | 主要产物 |
|---|---|---|
| S0 | 环境与硬件准入：芯片规格、驱动软件基线、真机环境与工具能力 | HardwareProfile、SoftwareProfile、CapabilityCertificate |
| S1 | 模型指纹与适配规划：模型结构识别、能力分类、资源上界、适配计划 | ArchFingerprint、CapabilityGap、AdaptationPlan |
| S2 | 图切分与权重适配：Graph/Card、tensor 映射、权重转换与内存窗口 | GraphPlan、TensorMapping、WeightManifest |
| S3 | 算子覆盖与 Host 数学基线：覆盖映射、Host Oracle 与 Golden | OperatorCoverage、Golden、StateContract |
| S4 | 主仓渲染、编译与静态审计：Patch、IR、布局、符号与可复现构建 | CandidatePatch、fatbin、BuildRecord |
| S5 | 微核与单层真机验证：计算、内存、DMA、P2P、同步、allocator | CapabilityCertificate、FailureSignature |
| S6 | 完整 Fresh 模型验证：端到端对拍与首分叉定位 | FreshRunResult、FirstDivergence |
| S7 | Stateful Prefill/Decode 验证：状态生命周期与逐 token 等价 | StatefulCertificate、FirstStateDivergence |
| S8 | 多卡 Pipeline 验证：rank/拓扑、通信、sync 代次与稳定性 | PipelineResult、CommunicationTimeline |
| S9 | 服务协议与资源生命周期验证：协议、逐 token、并发、取消恢复 | ServiceResult、ErrorMappingReport |
| S10 | 性能分析与闭环调优：Profile、单变量 A/B、正确性回归 | PerformanceRecord |
| S11 | 长稳、故障注入与发布验证 | ReleaseCandidate、长稳与回滚证据 |
| S12 | 资产签名与知识回流：Claim、失效条件与重验任务 | KnowledgeAsset、RevalidationTask |
附录B：术语表
| 术语 | 说明 |
|---|---|
| 任务契约 | 描述适配目标、执行位置与完成标准的结构化任务书，决定授权范围 |
| Plan / PlanGraph | Plan Agent 生成的不可变计划版本（界面显示为 r1、r5 等），决定任务顺序与门禁 |
| Gate | 阶段门禁。只依据同代证据与策略判定，不接受自评或口头结论 |
| Evidence | 不可变的原始证据（报告、对拍、时间线、快照、日志），结论由它支撑 |
| Attempt | 一次尝试。重试会创建新 Attempt，历史 Attempt 不被覆盖 |
| Lease | 真机资源的租约。所有设备操作必须持有效租约，过期即拒绝执行 |
| 首分叉（FirstDivergence） | 数值或状态第一次偏离参考实现的精确位置，是定位根因的入口 |
| 交付档位 | 验收深度与预算档次（如 smoke），决定本轮跑到哪一层验证 |
| 验收依据 | 支撑阶段结论的证据集合，可在阶段卡片直接打开 |
| 补充预算并继续 | 在历史案例原契约范围内追加预算与指令，继续推进执行 |