已关闭
[Doc]: AgentRegistry资料文档易用性不佳 #59
huangbin35创建于 7月30日关闭于 7月31日
7月30日 添加了label:sig/sig-agent-protocol
openJiuwen-bot
7月30日 评论:
7月30日 评论:
欢迎来到 openJiuwen 社区
Hey @huangbin35 , 感谢你对社区的贡献.
机器人使用手册
有关指令的使用,可以点击 此处 查看详情。开发人员可以在每个PR或Issue下方评论特定指令来触发机器人任务。
联系指引
有疑问可以联系 SIG: sig-agent-protocol ,
维护者是: @YiyangShao, @xinyu-jiuwen ,
审核者是: @gcw_hx9prznZ, @mingo007 .


7月31日 关闭了 issue
8月14日 issue状态由 TODO 改变为 DONE
📚 Documentation Issue Description
A. 资料易用性问题
A1. 版本号漂移:代码 v0.3.3 vs 文档 v0.3.2,且与Agent-protocol大版本号不一致
__version__ = "0.3.3";而 [README.md:3](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README.md#L3) 标注**v0.3.2**,[README_forAgentTeam.md:3](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README_forAgentTeam.md#L3) 同样标注**v0.3.2**,[a2x_registry/a2x/VERSION.md:3](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/a2x/VERSION.md#L3)当前版本: v0.3.2,且 VERSION.md 无 v0.3.3 变更记录条目pip show a2x-registry显示 0.3.3 与文档声明的 v0.3.2 不一致,造成版本困惑;VERSION.md 缺少 v0.3.3 变更条目导致变更追溯断裂--check是否覆盖 README/VERSION.md,如未覆盖应纳入A2. README 中 6 个评估结果链接指向不存在的目录
[summary](results/...)链接,指向results/20260323_*/summary.json,但项目根目录下results/目录不存在results/列为仓库顶层目录,但实际不存在,文档描述与实际不符results/目录,或上传至外部存储并在 README 中更新链接;2. 若不提交,应在.gitignore中显式声明results/,并修正 architecture_overview.md 的描述为"运行时生成"A3. 架构文档 gating 描述自相矛盾
### 2.4 a2x/ — A2X 分类构建与递归搜索(需 [vector]),但同文件 [§2.3 第 103-104 行](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/architecture_overview.md#L103-L104) 明确POST /api/datasets/{ds}/build(A2X 分类构建,纯 LLM)标记为 ✅(lite 可用);同样 [docs/a2x_design.md:276](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/a2x_design.md#L276) 注释a2x/ ... 需 [vector] extras与第 278 行traditional/ ... 需 [vector] extras均与 v0.1.7+ gating 修正矛盾a2x/和traditional/的"需 [vector] extras"标注A4. 客户端 SDK README §2.5 缺失 4 个公开方法
create_principal(第 108 行示例中使用但无方法条目)、heartbeat(第 234 行定义)、drain(第 258 行定义)、shutdown(第 273 行定义)heartbeat是心跳保活的核心方法,drain/shutdown是优雅关闭的关键方法,遗漏影响生产部署场景A5. 环境变量文档分散且部分缺失
A2X_REGISTRY_HOME在 [README.md:84](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README.md#L84) 提及,但 [README_forAgentTeam.md](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README_forAgentTeam.md) 和 [README_forDistributed.md](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README_forDistributed.md) 均未提及;②A2X_REGISTRY_CLUSTER_*系列变量在 [docs/cluster_design.md](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/cluster_design.md) 有完整表格,但实际部署指南 README_forDistributed.md 仅在 §5 提及A2X_REGISTRY_CLUSTER_ADVERTISE和HOLD_TIMEOUT,未引导至完整表格;③A2X_REGISTRY_AUTH_DATA环境变量仅在 [.gitignore:19](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/.gitignore) 注释中提及,无任何正式文档说明;④ 无.env.example文件汇总所有环境变量A2X_REGISTRY_HOME重定位数据目录;分布式部署用户在 README_forDistributed.md 中看不到完整的环境变量调参表;A2X_REGISTRY_AUTH_DATA仅在 .gitignore 注释出现,运维人员无法发现此配置项A2X_REGISTRY_HOME说明;2. 在 README_forDistributed.md §5 环境变量表格中补充完整A2X_REGISTRY_CLUSTER_*系列并链接至 cluster_design.md;3. 在 docs/auth_design.md 中补充A2X_REGISTRY_AUTH_DATA说明;4. 新增.env.example文件集中列出所有环境变量及默认值A6.
llm_apikey.example.json模板在 Agent Team README 中未引用~/.a2x_registry/llm_apikey.json配置路径,但未指向 [a2x_registry/llm_apikey.example.json](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/llm_apikey.example.json) 模板文件参考 a2x_registry/llm_apikey.example.json 模板的指引A7. 增量构建模块标记"待实现"但无明确计划
A2X 增量构建模块设计文档(待实现),[docs/a2x_design.md:23](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/a2x_design.md#L23) 标注状态为"待实现",但 VERSION.md 中无何时实现的计划说明B. 工具易用性问题
B1. ui/launcher.py 缺少 Node.js/npm 缺失的友好错误提示
subprocess.run("npm install", ..., shell=True)和第 85 行subprocess.Popen("npm run dev ...", shell=True)时,未检测npm/node是否存在于 PATH。若 Node.js 未安装,用户会收到 Python 抛出的FileNotFoundError/OSError原始异常python ui/launcher.py时若未安装 Node.js,看到的是不可读的 Python traceback,而非"Node.js is required, please install it from https://nodejs.org"的友好提示_start_frontend_dev()开头增加shutil.which("npm")检测,不存在时打印清晰提示并退出B2. ui/launcher.py 缺少端口占用的友好错误提示
uvicorn.run(..., port=args.port),无 try/except 捕获端口占用场景。端口被占用时 uvicorn 抛出SystemExit+ tracebackuvicorn.run()调用前增加端口可用性检测(如socket.bind),或 try/except 捕获后给出清晰的端口占用提示B3. 评估模块 error_analysis.py 硬编码数据集路径
Path('database/ToolRet_clean/taxonomy/taxonomy.json')、Path('database/ToolRet_clean/taxonomy/class.json')、Path('database/ToolRet_clean/service.json'),数据集名ToolRet_clean被固化ToolRet_clean数据集上运行错误分析时,即使config.json中提供了正确路径,默认 fallback 仍指向错误的数据集;从非项目根目录运行时路径完全失效config.json必须读取路径,缺失时报错而非 fallback 到ToolRet_cleanB4. cluster CLI 模块 docstring 与实际实现不一致
init和status两个命令(标注为"Commands (M0)"),并说"add-peer/rm-peerarrive with the session milestone"。但实际 [build_parser() 第 125-180 行](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/cluster/cli.py#L125-L180) 已实现add-peer、rm-peer以及完整的set add/remove/show声明式成员管理子命令help(a2x_registry.cluster.cli)或阅读源码 docstring 时,无法发现set子命令系列已实现,可能误以为仍需等待"session milestone"B5. auth CLI reset-admin 子命令参数缺少 help 描述
reset-admin子命令的 4 个参数--confirm、--handle、--admin-token、--data-dir均无help=描述字符串,而同文件init子命令的参数均有 help 描述a2x-registry auth reset-admin --help时,这 4 个参数无说明文字,不清楚各参数用途help=描述字符串,与 init 子命令风格一致B6. 多处 ThreadPoolExecutor max_workers 为裸魔法数字
ThreadPoolExecutor(max_workers=N)使用裸数字无命名常量或环境变量覆盖:[a2x_registry/backend/routers/search.py:19](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/backend/routers/search.py#L19)max_workers=4、[a2x_registry/backend/routers/dataset.py:39](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/backend/routers/dataset.py#L39)max_workers=2、[a2x_registry/backend/services/search_service.py:142](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/backend/services/search_service.py#L142)max_workers=20、[a2x_registry/register/service.py:1581](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/register/service.py#L1581)max_workers=10A2X_REGISTRY_SEARCH_WORKERS)可配,参照 cluster 模块ClusterConfig.from_env()的设计模式B7. llm_client.py 默认 fallback URL 硬编码 DeepSeek
base_url默认 fallback 硬编码为"https://api.deepseek.com/chat/completions",用于兼容旧版单 provider 配置B8. 无 .env.example 文件
.env.example文件,环境变量文档散布在 [common/paths.py](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/common/paths.py) docstring、[cluster/config.py](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/cluster/config.py)from_env()方法、[README_forDistributed.md](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README_forDistributed.md) 表格等多处.env.example文件,集中列出A2X_REGISTRY_HOME、A2X_REGISTRY_CLUSTER_*、A2X_REGISTRY_AUTH_DATA、A2X_FRONTEND_DIST_DIR、NO_PROXY等所有环境变量及默认值问题汇总表
Improvement and Fix Suggestions
Version Information
develop分支,commit d7fa3cc3bc8979feab193b13707a23de672263a4
Thanks for your contribution 🎉!