已关闭
[Doc]: AgentRegistry资料文档易用性不佳 #59
huangbin35创建于  7月30日关闭于  7月31日
huangbin35
huangbin35成员
7月30日 创建

📚 Documentation Issue Description

A. 资料易用性问题

A1. 版本号漂移:代码 v0.3.3 vs 文档 v0.3.2,且与Agent-protocol大版本号不一致

项目 详情
问题定位 [a2x_registry/init.py:19](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/init.py#L19) __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 变更条目导致变更追溯断裂
改进建议 1. 将 README.md、README_forAgentTeam.md 的版本号更新为 v0.3.3;2. 在 VERSION.md 补充 v0.3.3 变更条目;3. 检查 [scripts/bump_version.py](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/scripts/bump_version.py) 的 --check 是否覆盖 README/VERSION.md,如未覆盖应纳入

A2. README 中 6 个评估结果链接指向不存在的目录

项目 详情
问题定位 [README.md:21-35](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README.md#L21-L35) 包含 6 个 [summary](results/...) 链接,指向 results/20260323_*/summary.json,但项目根目录下 results/ 目录不存在
影响分析 用户点击评估结果链接返回 404,无法查阅评估详情;[docs/architecture_overview.md:71](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/architecture_overview.md#L71) 将 results/ 列为仓库顶层目录,但实际不存在,文档描述与实际不符
改进建议 1. 将评估结果数据提交至 results/ 目录,或上传至外部存储并在 README 中更新链接;2. 若不提交,应在 .gitignore 中显式声明 results/,并修正 architecture_overview.md 的描述为"运行时生成"

A3. 架构文档 gating 描述自相矛盾

项目 详情
问题定位 [docs/architecture_overview.md:119](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/architecture_overview.md#L119) 标题写 ### 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 修正矛盾
影响分析 根据 [VERSION.md](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/a2x/VERSION.md) v0.1.7 记录,A2X 搜索/Traditional 搜索/A2X 分类构建已修正为纯 LLM 工作流,lite 默认可用,但架构文档标题仍标注"需 [vector]",导致用户误以为需要安装数百 MB 的 ML 依赖才能使用 A2X 搜索
改进建议 1. 修正 architecture_overview.md §2.4 标题移除"需 [vector]";2. 修正 a2x_design.md 目录结构注释中 a2x/ 和 traditional/ 的"需 [vector] extras"标注

A4. 客户端 SDK README §2.5 缺失 4 个公开方法

项目 详情
问题定位 [client/README.md §2.5](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/client/README.md) 声明"下面列出本文档涵盖的通用方法",但实际遗漏了 [client/a2x_registry_client/client.py](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/client/a2x_registry_client/client.py) 中定义的 4 个公开方法:create_principal(第 108 行示例中使用但无方法条目)、heartbeat(第 234 行定义)、drain(第 258 行定义)、shutdown(第 273 行定义)
影响分析 开发者通过 README 查阅 SDK 方法时,无法发现这 4 个方法的存在与用法。heartbeat 是心跳保活的核心方法,drain/shutdown 是优雅关闭的关键方法,遗漏影响生产部署场景
改进建议 在 client/README.md §2.5 补充这 4 个方法的方法说明(输入/返回/错误),与现有方法条目格式一致

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 文件汇总所有环境变量
影响分析 Agent Team 用户不知道可用 A2X_REGISTRY_HOME 重定位数据目录;分布式部署用户在 README_forDistributed.md 中看不到完整的环境变量调参表;A2X_REGISTRY_AUTH_DATA 仅在 .gitignore 注释出现,运维人员无法发现此配置项
改进建议 1. 在 README_forAgentTeam.md 补充 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 中未引用

项目 详情
问题定位 [README_forAgentTeam.md:26](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/README_forAgentTeam.md#L26) 提及 ~/.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) 模板文件
影响分析 Agent Team 用户按 README_forAgentTeam.md 指引配置 LLM API key 时,不知道有现成模板可参考,需自行猜测 JSON 结构
改进建议 在 README_forAgentTeam.md 中补充 参考 a2x_registry/llm_apikey.example.json 模板 的指引

A7. 增量构建模块标记"待实现"但无明确计划

项目 详情
问题定位 [docs/incremental_design.md:1](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/incremental_design.md#L1) 标题为 A2X 增量构建模块设计文档(待实现),[docs/a2x_design.md:23](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/docs/a2x_design.md#L23) 标注状态为"待实现",但 VERSION.md 中无何时实现的计划说明
影响分析 用户看到设计文档以为功能已实现或即将实现,但实际无明确排期
改进建议 在 incremental_design.md 顶部补充"当前状态:未实现,预计 vX.X 版本交付"的状态说明,或在 Roadmap 中列出

B. 工具易用性问题

B1. ui/launcher.py 缺少 Node.js/npm 缺失的友好错误提示

项目 详情
问题定位 [ui/launcher.py:76-83](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/ui/launcher.py#L76-L83) 调用 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 缺少端口占用的友好错误提示

项目 详情
问题定位 [ui/launcher.py:131](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/ui/launcher.py#L131) 直接调用 uvicorn.run(..., port=args.port),无 try/except 捕获端口占用场景。端口被占用时 uvicorn 抛出 SystemExit + traceback
影响分析 端口 8000 被占用时用户看到 uvicorn 的原始报错,而非"Port 8000 is in use, try --port 8080"的友好提示
改进建议 在 uvicorn.run() 调用前增加端口可用性检测(如 socket.bind),或 try/except 捕获后给出清晰的端口占用提示

B3. 评估模块 error_analysis.py 硬编码数据集路径

项目 详情
问题定位 [a2x_registry/a2x/evaluation/error_analysis.py:31-33](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/a2x/evaluation/error_analysis.py#L31-L33) 硬编码了三个 CWD 相对路径: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 仍指向错误的数据集;从非项目根目录运行时路径完全失效
改进建议 移除硬编码 fallback,改为从 config.json 必须读取路径,缺失时报错而非 fallback 到 ToolRet_clean

B4. cluster CLI 模块 docstring 与实际实现不一致

项目 详情
问题定位 [a2x_registry/cluster/cli.py:6-12](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/cluster/cli.py#L6-L12) docstring 仅列出 init 和 status 两个命令(标注为"Commands (M0)"),并说"add-peer/rm-peer arrive 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"
改进建议 更新 cluster/cli.py 模块 docstring,列出所有已实现的命令(init/status/add-peer/rm-peer/set add/remove/show)

B5. auth CLI reset-admin 子命令参数缺少 help 描述

项目 详情
问题定位 [a2x_registry/auth/cli.py:159-162](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/auth/cli.py#L159-L162) 中 reset-admin 子命令的 4 个参数 --confirm、--handle、--admin-token、--data-dir 均无 help= 描述字符串,而同文件 init 子命令的参数均有 help 描述
影响分析 用户运行 a2x-registry auth reset-admin --help 时,这 4 个参数无说明文字,不清楚各参数用途
改进建议 为 reset-admin 的 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=10
影响分析 在不同硬件环境或负载场景下,用户无法通过配置调整并发度,需修改源码;缺乏命名常量也影响代码可读性
改进建议 将这些 max_workers 提取为命名常量或通过环境变量(如 A2X_REGISTRY_SEARCH_WORKERS)可配,参照 cluster 模块 ClusterConfig.from_env() 的设计模式

B7. llm_client.py 默认 fallback URL 硬编码 DeepSeek

项目 详情
问题定位 [a2x_registry/common/llm_client.py:199](file:///home/hb/a2x_registry/agent-protocol/AgentRegistry/a2x_registry/common/llm_client.py#L199) 将 base_url 默认 fallback 硬编码为 "https://api.deepseek.com/chat/completions",用于兼容旧版单 provider 配置
影响分析 SDK 默认 fallback 与特定 LLM 供应商(DeepSeek)耦合,使用其他供应商的用户在配置异常时可能误连至 DeepSeek API
改进建议 当配置缺失时,应报错提示"未配置 LLM provider"而非静默 fallback 到特定供应商 URL

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 等所有环境变量及默认值

问题汇总表

编号 类型 严重程度 问题摘要
A1 资料一致性 高 版本号漂移:代码 v0.3.3 vs 文档 v0.3.2,VERSION.md 缺 v0.3.3 条目
A2 资料完整性 高 README 中 6 个 results/ 链接指向不存在的目录
A3 资料准确性 高 架构文档 a2x/traditional gating 标注与 v0.1.7+ 修正矛盾
A4 资料完整性 中 客户端 SDK README §2.5 缺失 heartbeat/drain/shutdown/create_principal 方法说明
A5 资料完整性 中 环境变量文档分散,A2X_REGISTRY_HOME/CLUSTER_*/AUTH_DATA 在部分 README 缺失
A6 资料完整性 低 README_forAgentTeam.md 未引用 llm_apikey.example.json 模板
A7 资料完整性 低 增量构建模块标记"待实现"但无实现计划说明
B1 工具易用性 中 launcher.py 缺少 Node.js/npm 缺失的友好错误提示
B2 工具易用性 中 launcher.py 缺少端口占用的友好错误提示
B3 工具可移植性 中 error_analysis.py 硬编码 ToolRet_clean 数据集路径
B4 工具易用性 低 cluster CLI docstring 与实际实现不一致(遗漏 set 子命令)
B5 工具易用性 低 auth CLI reset-admin 参数缺少 help 描述
B6 工具可配置性 低 多处 ThreadPoolExecutor max_workers 为裸魔法数字
B7 工具可移植性 低 llm_client.py 默认 fallback URL 硬编码 DeepSeek
B8 工具易用性 中 无 .env.example 文件,环境变量配置分散

Improvement and Fix Suggestions

Version Information

develop分支,commit d7fa3cc3bc8979feab193b13707a23de672263a4

Thanks for your contribution 🎉!

likedislike
OopenJiuwen-bot成员
7月30日 添加了label:sig/sig-agent-protocol
openJiuwen-bot成员
7月30日 评论:

欢迎来到 openJiuwen 社区

Hey @huangbin35 , 感谢你对社区的贡献.

机器人使用手册

有关指令的使用,可以点击 此处 查看详情。开发人员可以在每个PR或Issue下方评论特定指令来触发机器人任务。

联系指引

有疑问可以联系 SIG: sig-agent-protocol ,
维护者是: @YiyangShao, @xinyu-jiuwen ,
审核者是: @gcw_hx9prznZ, @mingo007 .

likedislike
Zzhengw成员
7月31日 关联了pull request:fix(registry): Fix tooling usability issues from issue #59
OopenJiuwen-bot成员
7月31日 关闭了 issue
OopenJiuwen-bot成员
8月14日 issue状态由 TODO 改变为 DONE