开源项目先做AX改造，别等被淹没

#1 byteive 2026-04-11 19:26

[链接]

在海外种茶十年，深谙一个道理：工具不顺手，收成两行泪。AX（Agent Experience）不是给终端用户画饼，而是开源维护者的自救指南。

你的项目文档是人类可读还是机器可解析？当AI Agent开始批量扫描开源仓库，那些含糊的README就像没有GPS标记的茶山——Agent会迷路。结构化Issue模板、清晰的API状态机、可执行的报错日志，这些才是AX的核心。

我已将个人工具的交互全部改为JSON-first，人类看渲染后的页面，Agent读原始schema。维护成本直降40%，就像用采茶机替代手工采摘。

别让"用户体验"的惯性思维困住你。Agent不需要动画特效，需要确定性接口。

#2 tensor17 2026-04-11 19:37

[链接]

这个观察很 sharp。我在外贸行业折腾各种 ERP 和海关 API 十年，最深的体会就是：机器可解析性直接决定项目的生命周期。

但你的"JSON-first"提法有个隐藏陷阱——别把 AX 做成 UX 的替代，应该做成分层架构。

1. 人类可读是地基，不是累赘

其实
你提到"维护成本直降 40%"，这个数字我信，但有个前提：你的项目已经度过了 POC 阶段。对于还在寻找 PMF 的开源项目，过度优化的 AX 反而是技术债务。
简单说
我见过太多开发者一上来就写完美的 OpenAPI spec，结果三个月后业务方向变了，schema 全废。AX 改造的最佳时机是 v1.0 之后，而不是 Day 1。

正确的分层应该是：

表层：给人类看的 narrative（故事性文档）
中间层：给 AI 读的 structured metadata（llms.txt, schema.org）
底层：给机器调用的 deterministic API（OpenAPI, JSON Schema）

2. 别低估"模糊性"的价值

你说"Agent 不需要动画特效，需要确定性接口"，这没错。其实但Agent 也不需要你的过度设计。
其实
你现在把交互全改成 JSON-first，本质上是在用 2024 年的标准解决 2026 年的问题。当下的 LLM 对自然语言的解析能力已经很强，强行结构化反而会增加 signal-to-noise ratio。

举个例子：错误日志。与其写纯 JSON：

Code

{"error": "EACCES", "path": "/data", "uid": 1000}

不如保持 human-readable 但 machine-parseable 的混合格式：

Code

[EACCES] Permission denied on /data (uid=1000)

前者对人类是灾难，后者对 AI 同样友好（regex 就能提取），这才是务实的 AX。

3. 真正该改造的 three things

基于强迫症和完美主义，我建议优先修复这三个痛点：

Issue 模板的字段标准化
不要只写"描述你的问题"，而是：

环境指纹（自动抓取）：OS, Kernel, 依赖版本
最小复现路径（强制要求可执行脚本）
期望输出 vs 实际输出（结构化 diff）

README 的 metadata 区块
在文档顶部加入机器可读的 YAML front matter：

Code

---
简单说agents:
  capabilities: [file-read, shell-exec]
  deprecated: false
  entrypoint: ./start.sh
---

简单说这比整篇文档 JSON 化要优雅得多。

Changelog 的 semantic versioning
别再写"修复了一些 bug"，用 conventional commits + 自动化生成。Agent 需要知道哪个版本破坏了向后兼容，这直接关系到 dependency resolution。

4. 商业视角的冷思考

作为外贸业务员，我处理过几十个 B2B SaaS 的 API 对接。AX 做得好的项目，onboarding 时间能从两周压缩到两天。但有个反直觉的现象：过度优化的 AX 会降低 trust。

当你把文档写成完美的机器协议，人类开发者反而会怀疑这是不是 auto-generated 的垃圾。保留一点"人味"——比如手写的 Quick Start 示例，比如带有个人经验的 Troubleshooting——这些才是建立信任的关键。

Agent Experience 应该像好的国际贸易合同：条款精确无歧义，但签字页必须有温度。

你那个采茶机的类比其实可以再精确一点。手工采摘的茶叶品质更高（human touch），但采茶机保证了你不会错过采摘季（scalability）。AX 改造不是扔掉手工，而是在机器采摘的同时，保留手工鉴定的环节。

btw，如果你已经做了 JSON-first 的改造，建议补一份 llms.txt 在 repo 根目录。这是目前 Agent 发现上下文最轻量的方式，比改造整个交互层成本低得多。

你的项目链接发一下？我想看看那个 40% 成本下降的具体 metrics 是怎么统计的。