afxx 1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. afxx-1.0/LICENSE +202 -0
  2. afxx-1.0/MANIFEST.in +2 -0
  3. afxx-1.0/PKG-INFO +431 -0
  4. afxx-1.0/README.md +414 -0
  5. afxx-1.0/afxx/__init__.py +2 -0
  6. afxx-1.0/afxx/afx/__init__.py +2 -0
  7. afxx-1.0/afxx/afx/launcher.py +144 -0
  8. afxx-1.0/afxx/afx/platform.py +485 -0
  9. afxx-1.0/afxx/afx/replay.py +375 -0
  10. afxx-1.0/afxx/bundle.py +40 -0
  11. afxx-1.0/afxx/cli.py +499 -0
  12. afxx-1.0/afxx/common.py +167 -0
  13. afxx-1.0/afxx/config.py +494 -0
  14. afxx-1.0/afxx/credentials.py +130 -0
  15. afxx-1.0/afxx/environment/__init__.py +2 -0
  16. afxx-1.0/afxx/environment/bootstrap.py +271 -0
  17. afxx-1.0/afxx/environment/cann.py +351 -0
  18. afxx-1.0/afxx/environment/package_sources.json +9 -0
  19. afxx-1.0/afxx/environment/python.py +998 -0
  20. afxx-1.0/afxx/environment/runtime.py +422 -0
  21. afxx-1.0/afxx/environment/snapshot.py +66 -0
  22. afxx-1.0/afxx/evidence_bundle.py +176 -0
  23. afxx-1.0/afxx/execution.py +322 -0
  24. afxx-1.0/afxx/job_view.py +74 -0
  25. afxx-1.0/afxx/jobs.py +588 -0
  26. afxx-1.0/afxx/mcp_server.py +142 -0
  27. afxx-1.0/afxx/resources/config.example.yaml +42 -0
  28. afxx-1.0/afxx/source.py +236 -0
  29. afxx-1.0/afxx.egg-info/PKG-INFO +431 -0
  30. afxx-1.0/afxx.egg-info/SOURCES.txt +62 -0
  31. afxx-1.0/afxx.egg-info/dependency_links.txt +1 -0
  32. afxx-1.0/afxx.egg-info/entry_points.txt +2 -0
  33. afxx-1.0/afxx.egg-info/requires.txt +8 -0
  34. afxx-1.0/afxx.egg-info/top_level.txt +1 -0
  35. afxx-1.0/docs/AGENT_USAGE.md +182 -0
  36. afxx-1.0/docs/CONFIGURATION.md +174 -0
  37. afxx-1.0/docs/DESIGN.md +253 -0
  38. afxx-1.0/docs/LOCAL_DEPENDENCIES.md +52 -0
  39. afxx-1.0/docs/afxx-commands.md +317 -0
  40. afxx-1.0/pyproject.toml +25 -0
  41. afxx-1.0/setup.cfg +4 -0
  42. afxx-1.0/skills/afxxrepair/SKILL.md +165 -0
  43. afxx-1.0/skills/afxxrepair/agents/openai.yaml +4 -0
  44. afxx-1.0/skills/afxxrepair/assets/summary.yaml +33 -0
  45. afxx-1.0/skills/afxxrepair/references/platform-evidence.md +41 -0
  46. afxx-1.0/skills/afxxrepair/references/replay-evidence.md +56 -0
  47. afxx-1.0/tests/test_af_cann_env.py +248 -0
  48. afxx-1.0/tests/test_af_python_env.py +639 -0
  49. afxx-1.0/tests/test_afx_contract.py +217 -0
  50. afxx-1.0/tests/test_afx_launcher.py +96 -0
  51. afxx-1.0/tests/test_afxx.py +1137 -0
  52. afxx-1.0/tests/test_agent_interface.py +547 -0
  53. afxx-1.0/tests/test_credentials.py +153 -0
  54. afxx-1.0/tests/test_distribution.py +164 -0
  55. afxx-1.0/tests/test_environment_snapshot.py +105 -0
  56. afxx-1.0/tests/test_evidence.py +120 -0
  57. afxx-1.0/tests/test_evidence_bundle.py +101 -0
  58. afxx-1.0/tests/test_platform_adapter.py +479 -0
  59. afxx-1.0/tests/test_platform_queries.py +104 -0
  60. afxx-1.0/tests/test_platform_summary.py +73 -0
  61. afxx-1.0/tests/test_python_bootstrap.py +187 -0
  62. afxx-1.0/tests/test_replay_adapter.py +281 -0
  63. afxx-1.0/tests/test_status_view.py +148 -0
  64. afxx-1.0/tests/test_workflow_modules.py +119 -0
afxx-1.0/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
afxx-1.0/MANIFEST.in ADDED
@@ -0,0 +1,2 @@
1
+ recursive-include docs *.md
2
+ recursive-include skills *.md *.yaml
afxx-1.0/PKG-INFO ADDED
@@ -0,0 +1,431 @@
1
+ Metadata-Version: 2.4
2
+ Name: afxx
3
+ Version: 1.0
4
+ Summary: AFX Extensions: development and repair toolkit for AFX
5
+ License-Expression: Apache-2.0
6
+ Requires-Python: >=3.11
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: PyYAML<7,>=6
10
+ Requires-Dist: mcp<2,>=1.26
11
+ Provides-Extra: dev
12
+ Requires-Dist: pytest; extra == "dev"
13
+ Requires-Dist: jsonschema; extra == "dev"
14
+ Requires-Dist: build; extra == "dev"
15
+ Requires-Dist: ruff; extra == "dev"
16
+ Dynamic: license-file
17
+
18
+ # AFXX — AFX Extensions
19
+
20
+ AFXX 是适配 AFX 的开发与问题修复工具包,从本地工作区同步源码到 NPU 环境,构建和安装 AF,并管理 Python 环境、固定 seed 复跑及 AFX 平台验证。源码同步包含未提交修改,使用 npursync 传输冻结快照。
21
+
22
+ 安装后使用 `afxx` 命令;`afxx mcp` 提供 stdio MCP 接口。命令和远端任务共用同一套业务模块,上传文件从已安装的 wheel 中取得,无需保留本工具源码。源码仓库由配置指定,命令可在任意目录执行。
23
+
24
+ - [命令参考与参数矩阵](docs/afxx-commands.md)
25
+ - [配置说明与默认值](docs/CONFIGURATION.md) · [YAML 模板](afxx/resources/config.example.yaml)
26
+ - [Agent 调用约定](docs/AGENT_USAGE.md) · [问题修复 Skill](skills/afxxrepair/SKILL.md)
27
+ - [设计与模块边界](docs/DESIGN.md)
28
+
29
+ ## 工具目录
30
+
31
+ ```text
32
+ afxx/
33
+ ├── README.md
34
+ ├── pyproject.toml # wheel、依赖和命令入口
35
+ ├── afxx/ # Python 包
36
+ │ ├── cli.py # CLI 命令入口
37
+ │ ├── mcp_server.py # stdio MCP 到 CLI 协议适配
38
+ │ ├── resources/config.example.yaml # 带注释配置模板
39
+ │ ├── common.py # 文件、锁、进程等公共工具
40
+ │ ├── config.py # 配置加载与校验
41
+ │ ├── bundle.py # 远端运行文件清单
42
+ │ ├── source.py # 源码同步
43
+ │ ├── jobs.py # 远端作业协议
44
+ │ ├── execution.py # deploy/replay
45
+ │ ├── environment/ # 环境管理
46
+ │ │ ├── runtime.py
47
+ │ │ ├── snapshot.py
48
+ │ │ ├── python.py
49
+ │ │ ├── cann.py
50
+ │ │ └── package_sources.json
51
+ │ └── afx/ # AFX 接口适配
52
+ │ ├── replay.py
53
+ │ └── platform.py
54
+ ├── docs/ # Agent 规范、设计、本地依赖
55
+ └── tests/ # 单元与接口测试
56
+ ```
57
+
58
+ 内部模块通过 `afxx` 包导入;远端任务保留相同包结构。日常调用已安装的 `afxx`;agent 也可通过 `afxx mcp` 使用同一组命令。
59
+
60
+ 查看全部命令:`afxx help`。
61
+
62
+ ## 安装与配置
63
+
64
+ 本地需准备 **Python 3.11+(含 pip)、Git、Node.js 20+、npussh/npursync、OpenSSH 客户端和 rsync**,并确保命令在 PATH 中可用。npursync 随 npussh 提供;PyYAML 和 MCP SDK 随 AFXX wheel 自动安装。版本要求、安装方式及检查范围见 [本地依赖说明](docs/LOCAL_DEPENDENCIES.md#本地启动环境)。
65
+
66
+ 安装 AFXX 并登录 NPU 服务:
67
+
68
+ ```bash
69
+ python3 -m pip install /absolute/path/afxx-1.0-py3-none-any.whl
70
+ npussh login
71
+ npussh list
72
+ ```
73
+
74
+ 生成本地配置,默认保存到 `~/.config/afxx/config.yaml`:
75
+
76
+ ```bash
77
+ afxx config init --source /absolute/path/graph-autofusion
78
+ ```
79
+
80
+ 可用 `afxx config init --output` 指定其他位置。使用非默认位置时,后续命令需显式传 `--config /absolute/path/config.yaml`。
81
+ 所有命令默认读取 `~/.config/afxx/config.yaml`;仅 `--config` 显式覆盖。
82
+
83
+ 编辑生成的配置,填写连接环境、workflow_root 和远端 LLVM/LLD 路径。字段说明、路径推导和 Python/CANN 选项见 [配置文档](docs/CONFIGURATION.md)。
84
+
85
+ 源码目录由配置显式指定,工具目录可以放在仓库之外;部署仍遵循 graph-autofusion 的 build.sh、构建产物和安装约定。
86
+
87
+ ```bash
88
+ afxx doctor
89
+ ```
90
+
91
+ doctor 校验配置、本地连接工具和 npussh 登录。远端依赖由 init/check 及各操作的预检负责。
92
+
93
+ ## 命令与参数矩阵
94
+
95
+ 完整命令速查、必填参数、默认值、ID 类型、dry-run 和 MCP 行为见 [命令参考](docs/afxx-commands.md)。也可执行 `afxx <命令> --help` 查看当前安装版本的参数。
96
+
97
+ ## 初始化和更新环境
98
+
99
+ ```bash
100
+ afxx env init
101
+ afxx env check
102
+ # 修改配置后更新 torch_npu / AFX
103
+ afxx env update
104
+ ```
105
+
106
+ init 自动上传配置并准备 Python 3.11、CANN 和专用 venv。update 更新 torch_npu/AFX,保留现有 CANN。init/update 默认跟随远端日志;`--detach` 仅提交任务,后续用 status 查询。
107
+
108
+ 配置 platform 后,init 优先复用本地 token 文件,缺失时在交互终端隐藏输入;环境成功后自动同步到 NPU。路径留空时使用 `~/.config/afxx/auth/afx.token` 和 `<workflow_root>/auth/afx.token`。非交互调用需预先准备本地文件;detach/MCP 提交后通过 status/wait 完成成功后的同步。
109
+
110
+ 首次初始化、包源、版本选择和失败恢复规则见 [环境配置](docs/CONFIGURATION.md#初始化和更新环境)。
111
+
112
+ ## 部署源码与 AF
113
+
114
+ ```bash
115
+ afxx deploy --request-id deploy-001
116
+ afxx status --job-id <job-id>
117
+ ```
118
+
119
+ 提交返回 job ID。远端先采集实际环境快照、检查运行依赖,再同步源码,执行 `bash build.sh --pkg --enable-mlir -j 8`,将本轮产物写入 job 的 packages/,随后校验并升级安装 AF。安装后验证实际加载的 pyautofuse、adapter、codegen 文件与本轮构建产物一致。
120
+
121
+ 日常任务现场采集环境快照,不比对历史安装清单或检查缓存 wheel;依赖无法加载或 AF 部署产物被替换仍报错。详见 [Job 环境快照](docs/CONFIGURATION.md#job-环境快照)。
122
+
123
+ `deploy --issue-id F152` 关联领取上下文,在编包期间续租。部署完成后,通过独立的 `issue verify` 命令提交平台验证。
124
+
125
+ ```bash
126
+ # 离线校验并生成本地快照
127
+ afxx deploy --dry-run
128
+
129
+ # 查看远端任务日志
130
+ npussh <environment> 'tail -n 100 /remote/workflow-state/<job-id>/job.log'
131
+ ```
132
+
133
+ 同步包含受版本控制文件及未忽略的新文件,排除凭据、agent 私有配置、构建目录和依赖缓存。每次生成完整目录快照及哈希清单。删除操作仅处理上一份托管清单拥有的源码文件。`.af-workflow` 标识远端源码归属,手工修改托管文件会阻止同步。
134
+
135
+ 同一源码目录的同步/编译串行,安装与受管理的复测通过锁协调。部署直接在专用 build 目录增量编译和覆盖产物,旧版 build 指纹会在下次部署时移除。AF 覆盖安装失败会使当前部署失效;Python 更新支持锁文件回滚,AF/CANN 安装失败需检查现场并恢复安装。
136
+
137
+ ## AFX 平台修复流程
138
+
139
+ 先完成 [平台连接配置](docs/CONFIGURATION.md#平台连接)。
140
+
141
+ ### 直接领取平台编号
142
+
143
+ 平台提供 `/api/issues` 且 agent token 拥有 `issue` 权限时,可以直接使用功能、精度或性能问题编号(F、A、P 加 1 至 9 位数字)。
144
+
145
+ ```bash
146
+ afxx issue claim --issue-id F152
147
+ afxx issue preview --issue-id F152
148
+ afxx issue renew --issue-id F152
149
+ afxx deploy --issue-id F152 --request-id deploy-F152-1
150
+ # 用 status --job-id 确认这次部署成功后提交
151
+ afxx issue verify --issue-id F152 --job-id <deploy-job-id>
152
+ ```
153
+
154
+ 领取成功后终端显示问题摘要。完整回执保存在本机 `issues/<issue_id>.json`;编号问题的 preview 默认输出缩进 JSON,包含失败摘要和去重后的全部 nnsmith seed。若领取回执被截断,preview 会从平台分页读取当前受影响的用例。加 `--full` 可查看领取时保存的复现详情和相关知识。编号领取可显式传 `--request-id`;省略时 CLI 在发送前将生成的 ID 写入 stderr,重试使用同一个 ID。修复期间按租约到期时间提前续租,关联部署期间 workflow 自动续租。验证以实测 AF 版本及 pyautofuse.so 哈希提交,返回 `data.round_no`。平台按芯片和包身份调度已注册客户端。
155
+
156
+ ### 平台分配与结果查询
157
+
158
+ 省略 `--issue-id` 时,平台分配一个待修复问题;没有任务时返回 `data=null`。
159
+
160
+ ```bash
161
+ afxx issue claim --request-id claim-001
162
+ # 使用 verify 返回的 round_no
163
+ afxx issue status --issue-id F152 --round-no 1
164
+ afxx issue wait --issue-id F152 --round-no 1 --timeout 3600
165
+ ```
166
+
167
+ verify 在远端核对部署记录与实际加载的 AF,确认官方客户端已启动后向 `/api/issues/{id}/verify` 提交 lease_id、fix_version、fix_sha256 和 request_key。job 的 platform.json 保存固定请求和回执。网络失败后重试同一部署会复用请求键;不同修复使用新的部署 job。
168
+
169
+ status/wait 查询指定 verify 轮次及紧随其后、包身份一致的 regress 轮次。回归仍在执行时不会把验证通过视为整个流程通过;后续修复的轮次不会覆盖本次结果。失败或超时返回错误码及轮次详情,超时后可继续查询同一 round_no。修复总结由平台处理。
170
+
171
+ ### 查询平台定位信息
172
+
173
+ 以下命令只读,不需要先 claim,也不连接 NPU:
174
+
175
+ ```bash
176
+ afxx issue detail --issue-id F152
177
+ afxx issue tasks --issue-id F152 --round-no 1
178
+ afxx issue regression-preview --issue-id F152
179
+ afxx execution show --exec-uuid <exec_uuid>
180
+ ```
181
+
182
+ `detail` 返回生命周期、租约、轮次和事件;`tasks` 查询实际验证或回归轮次,返回 issue_id、round_no 和 tasks。回归候选预览不等于最终执行集。`execution show` 使用执行 UUID(不是数值 exec_id),返回环境、Shape、日志及平台的 log_truncated/log_missing 标记;不将截断日志标为完整。修复总结先在本地整理、人工检视,再通过独立的 `issue summarize` 显式发布。
183
+
184
+ ### 检视后提交修复总结
185
+
186
+ 先将已检视的总结保存为本地 `summary.yaml`(直接填写知识字段,不加 knowledge 外层)。YAML 是 AFXX 的本地输入格式,便于编辑和检视;平台接收的是 AFXX 转换后的 JSON 请求,并不要求 YAML:
187
+
188
+ ```yaml
189
+ kind: bugfix_function
190
+ title: "修复调度边界条件"
191
+ symptom: "原始 seed 在指定 Shape 下编译失败"
192
+ root_cause: "边界条件处理不完整"
193
+ solution: "修正边界条件,并补充对应回归测试"
194
+ fix_ref: "实际修复 commit SHA"
195
+ ```
196
+
197
+ ```bash
198
+ afxx issue summarize --issue-id F152 \
199
+ --summary-file /absolute/path/summary.yaml --request-id summary-F152-001
200
+ ```
201
+
202
+ 这是本地发起的平台写操作,不连接 NPU。需要本地领取记录、有效租约、knowledge 权限和平台 summarizing 状态。成功返回 issue_id、status=resolved 和 knowledge_id。网络失败重试同一命令;同一 request-id 固定总结内容、租约和平台,改变内容会报 REQUEST_CONFLICT。verify、回归及修复 skill 都不会自动调用它。
203
+
204
+ 必填字段为 kind/title/symptom/root_cause/solution。kind 使用 AFX 类型,如 bugfix_function、bugfix_accuracy 或 perf_tuning;可选字段包括 keywords、ops、dtypes、backends、graph_pattern、applicability、version_range、fix_ref、body_md。具体类型和长度由平台校验。提交后知识会发布,不只是保存草稿。
205
+
206
+ ## AFX 常驻客户端
207
+
208
+ AFXX 在本地控制远端任务;AFX 官方客户端在 NPU 上独立运行,负责心跳、上传、复测领取和平台更新。`issue verify` 提交前调用官方命令启动客户端,使用配置中的 venv/CANN 和 replay.devices。相同环境的已有进程直接复用;启动命令或环境变量变化时报错。AF 包哈希变化时复用已有客户端,其缓存刷新能力取决于 AFX 实现。AFXX 不实现上传、心跳或复测循环。
209
+
210
+ 配置 `platform.client_token_file` 后无需手工启动。客户端文件位于远端 state_dir 的上一级目录下的 `afx-client/`,日志为 `client.log`。也可在独立 HOME 中手工启动官方客户端,例如:
211
+
212
+ ```bash
213
+ source /mnt/workspace/af-workflow/Ascend/cann/set_env.sh
214
+ source /mnt/workspace/af-workflow/venv/bin/activate
215
+ export AUTOFUSEX_HOME=/mnt/workspace/af-workflow/afx
216
+ mkdir -p "$AUTOFUSEX_HOME/results"
217
+ afx platform client run --endpoint https://autofuse.online \
218
+ --token-file /absolute/path/client.token \
219
+ --results "$AUTOFUSEX_HOME/results/results.sqlite" --retest --device npu:0
220
+ ```
221
+
222
+ SQLite 数据库由 AFX 创建,不必手工建立空文件。`--retest` 启用平台复测任务领取;客户端需报告与 verify 提交相符的后端版本、哈希和芯片信息。包更新、注册和调度遵循 AFX 自身行为。AFXX 的环境锁仅协调 AFXX 任务,不代表独立客户端也持有这些锁。
223
+
224
+ ### 遗留问题:手动 replay 临时占用单卡
225
+
226
+ 状态:待实现(2026-11-20)。当前平台复测与手动 replay 通过设备锁竞争,没有手动 replay 优先级保证。
227
+
228
+ 预期平时所有卡都可执行平台任务。手动 replay 到来时,优先使用空闲卡;否则选定一张卡,暂停向该卡启动新任务,等待当前任务结束后执行 replay,其他卡继续工作。replay 完成、失败或取消后自动恢复该卡的平台任务。
229
+
230
+ AFX 需要提供按卡独立执行和本机让卡协调,AFXX 调用该能力并展示等待状态。让卡本身在本机完成;已领取但未执行的平台任务需要明确续租或归还策略,优先评估按空闲卡领取、避免预取积压任务的方式。平台接口是否需要扩展待实现时核实。共享 AF 安装目录的 deploy 仍需协调所有正在使用该包的任务。
231
+
232
+
233
+ ## 独立 seed 复跑
234
+
235
+ ```bash
236
+ afxx replay \
237
+ --job-id <deploy-job-id> --seed <seed>
238
+
239
+ afxx replay \
240
+ --job-id <deploy-job-id> --seeds-file /absolute/path/seeds.txt
241
+ ```
242
+
243
+ seed 文件每行一个 seed。replay 校验当前部署、环境清单和加载库,创建独立 HOME、缓存和结果数据库。单 seed 使用第一张配置卡,批量模式使用配置的 workers、设备列表和 timeout。
244
+
245
+ Shape 数量由 AFX 解码 seed 得到:静态为 1,动态为 2–8。结果通过 `fuzz maintenance results` 分页读取及查询 attempt 详情,不直接读取 SQLite 表。
246
+
247
+ 通过要求为执行命令成功、CPU/AF-MLIR attempt 均为 ok、seed/backend/shape 完整且无重复。AF-MLIR correctness 必须为 pass,CPU 参考后端允许 not_checked 或 pass。unsupported、缺失结果和目标后端未比较均判失败。
248
+
249
+ 独立 replay 默认只保存结果。启用 upload 或传 --upload 时使用 upload.sync_config_path 请求 AFX 同步,--no-upload 可覆盖。result.json 中 upload=pending 表示同步已请求,服务端接收情况需另查。平台客户端会上传自己领取的验证任务结果。
250
+
251
+ ## 环境清单、产物与清理
252
+
253
+ 本地状态根目录由 `local.state_dir` 指定,默认是 `~/.local/state/graph-autofusion/dev_workflow/jobs`:
254
+
255
+ ```text
256
+ <local.state_dir>/
257
+ ├── requests/ request-id → 冻结任务的幂等索引及锁
258
+ ├── issues/
259
+ │ ├── <issue-id>.json 领取响应、目标环境及租约
260
+ │ └── <issue-id>/summary.yaml skill 生成、待人工检视的修复总结
261
+ └── <job-id>/
262
+ ├── config.yaml 本地提交时冻结的配置
263
+ ├── request.json 请求及提交记录
264
+ ├── source.json deploy 源码清单、哈希及快照清理结果
265
+ ├── snapshot/ 待同步源码的普通目录树,启动确认后清理
266
+ └── afxx/ 随任务上传的执行模块
267
+ ```
268
+
269
+ 远端默认布局如下;显式配置路径时以实际配置为准。job 内文件按任务类型和执行阶段生成,不是每个任务都有全部文件:
270
+
271
+ ```text
272
+ <workflow_root>/
273
+ ├── python/ 托管 Python 及引导工具
274
+ ├── venv/ 专用 Python 环境
275
+ ├── Ascend/cann/ CANN 安装目录
276
+ ├── auth/afx.token 默认平台凭据,不属于 job 产物
277
+ ├── graph-autofusion/ 同步后的源码
278
+ │ ├── .af-workflow 托管源码归属和哈希清单文件
279
+ │ └── build/ 复用的编译目录
280
+ ├── workflow-state/<job-id>/
281
+ │ ├── config.yaml 提交配置;init/update 成功后附带环境锁
282
+ │ ├── environment.json 实际环境、采集错误及 Python 依赖检查
283
+ │ ├── request.json 任务请求
284
+ │ ├── launch.json 远端启动记录
285
+ │ ├── status.json 当前阶段与终态
286
+ │ ├── source.json 源码清单及快照清理结果
287
+ │ ├── snapshot/ 同步校验成功后清理
288
+ │ ├── packages/ 本轮 AF run 包
289
+ │ ├── result.json 部署/replay/环境操作结果及产物索引
290
+ │ ├── platform.json verify 固定请求及平台回执
291
+ │ ├── job.log 任务日志
292
+ │ └── uv.log Python 包安装日志
293
+ ├── workflow-results/<job-id>/
294
+ │ ├── results.sqlite AFX replay 结果数据库
295
+ │ ├── dump/ AF/GE 图、MLIR 等定位产物
296
+ │ └── cache/ 编译缓存;其他日志/产物按实际执行生成
297
+ └── workflow-env-state/
298
+ ├── current.json 当前环境清单
299
+ ├── wheels/ 按哈希保存的 torch_npu/AFX wheel
300
+ └── locks/ Python 依赖锁文件
301
+ ```
302
+
303
+ replay 终态下载的证据在本机 `/tmp`,响应中的 `evidence_path` 给出准确路径:
304
+
305
+ ```text
306
+ /tmp/afxx-evidence-<uid>/<job-id>-<环境标识>/
307
+ ├── evidence.json 完整清单、远端/本地路径、大小及哈希
308
+ ├── job/ 下载的报告、任务日志及调试文件
309
+ └── results/ 下载的完整 dump、日志、缓存和结果数据库
310
+ ```
311
+
312
+ CANN 全量安装包临时下载到 **远端** `/tmp/af-cann-<job-id>-*/`,与本地 evidence 目录不同。
313
+
314
+ 源码快照 snapshot/ 为普通目录树。确认远端启动后清理本地副本,远端同步校验成功后清理远端副本。状态不明确时保留现场,dry-run 保留快照。源码清单和部署引用继续用于校验,删除快照后需另行保留源码才能恢复未提交修改。
315
+
316
+ 完整 CANN 下载包在安装成功后清理,失败时保留。AF run 包、共享 wheel、锁文件和任务记录持续保留,按需要归档。当前部署注册表通过路径和 SHA-256 引用 result.json,后者引用 source.json;后续复跑依赖这些文件。
317
+
318
+ init/update 成功后的冻结配置可用于重建环境,操作与约束见 [从冻结配置重建环境](docs/CONFIGURATION.md#从冻结配置重建环境)。
319
+
320
+ ## 验证工具本身
321
+
322
+ ```bash
323
+ python3 -m pytest tests -q
324
+ ```
325
+
326
+ 测试使用临时目录、Git/rsync 和构建、平台、设备接口夹具,覆盖同步、幂等、更新回滚、环境冻结、结果判定和平台验证轮次。真实编包、NPU 执行及平台联调需在配置的目标环境验证。
327
+
328
+ 测试分层:业务规则和边界在所属模块测试;deploy/replay 编排覆盖成功路由与各阶段失败,不对无关开关做全组合;CLI 验证公开路由和响应;MCP 只验证 stdio 握手、帮助、命令执行及错误封装。各命令共用的远端 bundle 只做一次独立导入验证。幂等、并发、回滚、源码保护和结果判定仍保留故障场景覆盖。
329
+
330
+ 发布前必须指定 AFX 源码运行完整测试及真实契约测试:
331
+
332
+ ```bash
333
+ AFX_SOURCE=/absolute/path/Autofuse-Debugger python3 -m pytest tests -q --require-afx-contracts
334
+ ```
335
+
336
+ 日常测试未设置 AFX_SOURCE 时跳过真实契约;发布验证的 `--require-afx-contracts` 在缺少源码路径时直接失败,不能将跳过当成兼容通过。
337
+
338
+ 契约测试需要 pytest、PyYAML、jsonschema 及对应 AFX 接口的运行依赖;调用真实的 AFX seed、结果 CLI 和修复服务逻辑,使用临时数据库,不连接生产平台。
339
+
340
+ ## MCP 接入
341
+
342
+ MCP 是可选接入方式:agent 可直接执行 `afxx` CLI,也可通过 MCP 调用同一套功能。`afxx mcp` 在本地由 agent 客户端启动,通过标准输入/输出(stdio)通信;不需要在 NPU 上启动 MCP 服务,也不需要配置 HTTP 地址。
343
+
344
+ ### 接入 Codex
345
+
346
+ 安装 AFXX wheel 后,在本地终端执行:
347
+
348
+ ```bash
349
+ # 查找 wheel 提供的 MCP 入口
350
+ command -v afxx
351
+
352
+ # 将上一条输出的绝对路径填到这里
353
+ codex mcp add afxx -- /absolute/path/to/afxx mcp
354
+ codex mcp list
355
+ ```
356
+
357
+ 默认使用 `~/.config/afxx/config.yaml`。如果要固定使用另一份配置,注册时将参数传给 afxx mcp:
358
+
359
+ ```bash
360
+ codex mcp add afxx -- /absolute/path/to/afxx mcp --config /absolute/path/config.yaml
361
+ ```
362
+
363
+ 两种注册方式选一种。注册后,在加载了该 MCP 的 agent 会话里请求:“使用 afxx MCP 查看 deploy 命令帮助”。应调用 `afxx_help`,无需执行真实部署。`codex mcp list` 只确认注册信息,工具调用成功才表示接入可用。
364
+
365
+ 绝对路径用于让客户端找到可执行文件;若 command 只写 `afxx`,客户端进程的 PATH 必须包含它所在的目录,args 中填写 `mcp`。实际远端操作还要求客户端环境能找到 npussh 等连接工具。
366
+
367
+ ### 其他支持 stdio 的客户端
368
+
369
+ 按客户端自己的 MCP 配置格式填写可执行文件路径。采用 mcpServers JSON 格式的客户端可参考下例;这段 JSON 不用于 Codex 的 config.toml:
370
+
371
+ ```json
372
+ {
373
+ "mcpServers": {
374
+ "afxx": {
375
+ "command": "/absolute/path/to/afxx",
376
+ "args": ["mcp"]
377
+ }
378
+ }
379
+ }
380
+ ```
381
+
382
+ 如需指定其他配置,将 args 改为 `["mcp", "--config", "/absolute/path/config.yaml"]`。无需手动在终端常驻运行 afxx mcp,客户端负责启动它。
383
+
384
+ 提供两个工具:`afxx_help(command)` 查询命令参数;`afxx_run(command, arguments, config)` 执行命令并返回原有 JSON 响应,失败同时标记 MCP `isError`。例如 `{"command":"deploy","arguments":["--request-id","fix-001"]}`,随后用 `{"command":"status","arguments":["--job-id","<job-id>"]}` 查询。`arguments` 是参数数组,不经过 shell。
385
+
386
+ `init/update` 通过 MCP 自动使用 `--detach`,不会占住会话等待远端安装;其他命令保持 CLI 行为。取消 MCP 调用停止本地 CLI 子进程,已提交的远端任务仍可通过 job ID 查询。标准输出仅用于 MCP 协议,诊断日志写到标准错误。只有公开命令可通过 MCP 调用;内部 worker 入口不开放。MCP 不额外增加平台行为或自动提交 verify。
387
+
388
+ ## 构建 wheel
389
+
390
+ ```bash
391
+ uv venv --python 3.11
392
+ uv pip install -e '.[dev]'
393
+ .venv/bin/python -m pytest tests -q
394
+ .venv/bin/python -m build
395
+ ```
396
+
397
+ 产物位于 `dist/`。wheel 包含远端运行模块、包源配置和 YAML 模板,不包含用户配置、token、源码快照或本地状态。本工具采用 [Apache License 2.0](LICENSE)。
398
+
399
+ ## 发布到 PyPI
400
+
401
+ 发布工作流位于 [publish.yml](.github/workflows/publish.yml),推送 `v*` tag 时触发。流程检查 tag 与 `pyproject.toml` 版本一致,运行完整测试(包括固定 AFX commit 的契约测试),构建并检查 wheel/sdist,验证 wheel 安装,最后上传 PyPI。普通分支推送不会发布。
402
+
403
+ 首次发布前需配置:
404
+
405
+ 1. GitHub 仓库 `gaosher/afxx` 的 Settings → Environments 中创建 `pypi`。
406
+ 2. 在 [PyPI Publishing](https://pypi.org/manage/account/publishing/) 添加 GitHub Trusted Publisher:项目 `afxx`、Owner `gaosher`、Repository `afxx`、Workflow `publish.yml`、Environment `pypi`。已有项目则在项目的 Publishing 页面配置。无需保存 PyPI token;首次发布时包名必须可用。
407
+
408
+ 提交代码与版本号后发布,例如 `pyproject.toml` 中版本为 `1.0`:
409
+
410
+ ```bash
411
+ git push -u origin main
412
+ git tag v1.0
413
+ git push origin v1.0
414
+ ```
415
+
416
+ 到 GitHub Actions 查看结果。后续发布需递增版本号,不覆盖已发布文件。AFX 契约源码通过 HTTPS 从 GitCode 拉取,版本固定在工作流的 `AFX_REVISION`;更新该值时需重新验证契约测试。源码获取或测试失败都会阻止发布。
417
+
418
+ ## 问题修复 Skill
419
+
420
+ `afxxrepair` 编排领取、复现定位、修改、deploy、verify、回归和修复提交,最终生成带修复及验证证据的可提交 summary.yaml,供人工检视后使用 issue summarize 发布。使用现有 AFXX CLI/MCP,不另实现客户端。安装到 Codex 的 skills 目录(目标已存在时先检查本地修改):
421
+
422
+ ```bash
423
+ mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
424
+ cp -R skills/afxxrepair "${CODEX_HOME:-$HOME/.codex}/skills/"
425
+ ```
426
+
427
+ 调用示例:`使用 $afxxrepair 修复 AFX issue F152,验证和回归通过后 commit,等待检视。`
428
+
429
+ replay 到达 success/failed 后,本地 `status` 或 `status --wait` 自动将完整 dump、日志、报告、结果数据库和清单下载到 `/tmp/afxx-evidence-<uid>/<job-id>-<环境标识>/`。返回仅包含 job_id、state、evidence_path 和 failures(attempt_id、seed、backend、shape_indices、stage、简短 error);失败超过 20 项时附数量和截断标记。异步提交后仍需调用 status/wait,远端不会主动推送文件。重复查询校验并复用本地文件,不重复下载。 单个执行可用 `status --attempt <id> --fields ...` 按字段查询。详见 [证据读取说明](docs/AGENT_USAGE.md#status-概要字段查询与等待)。
430
+
431
+ 定位复现可使用 `afxx replay --dump --job-id <deploy-job-id> --seed <seed>`;`--dump` 仅覆盖本次任务并保存到 job 配置,原配置文件不变。