Astryx错误码设计哲学Append-only稳定标识符让程序可以安心分支【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个开源设计系统内置一套专为 AI Agent 和 CI 脚本设计的 CLI 工具。它最巧妙的细节之一是错误码的设计哲学采用Append-only只追加的稳定错误码标识符让程序可以放心地对错误做分支判断而不用害怕明天升级后逻辑就悄悄失效。为什么错误码比错误信息更重要传统命令行工具失败时会打印一句人类可读的报错比如找不到组件 Button。人看着没问题但程序怎么办只能去匹配文字。一旦某天官方把这句话改写成别的措辞、或者翻译成了别的语言你的脚本就静默断裂了——这是所有基于字符串匹配的错误处理最大的隐患。Astryx 的 CLI 把给程序看和给人看彻底分开了。它的目标调用者就是 AgentAgent 在子进程里运行 CLI读取 JSON 输出然后无人值守地决定下一步动作架构依据见 cli-surface.md。JSON 信封机器友好的统一输出Astryx CLI 加--json参数后所有输出都收敛为两种固定信封格式实现在 json.mjs成功{ apiVersion, type, data }可附meta失败{ apiVersion, error, code }可附suggestions关键点在于失败信封里有两个字段分工明确字段给谁看能否变error人类随时可以改措辞、本地化code程序永不变一旦发布就冻结架构文档把它写成了正式不变量INV3——代码即契约文字不是消费方只对code分支永远不要对error字符串做匹配。Append-only只追加不改写不删除Append-only 是这套设计哲学的核心用一句大白话说就是错误码表是一张只允许往后加新条目的清单。✅ 可以新增遇到新的失败场景追加一个ERR_开头的新码❌ 不可以改义已发布错误码的含义永远不变❌ 不可以删除哪怕某个场景不存在了码也保留为什么这么固执因为每个错误码都是一次对外的承诺。下游可能有几百个 Agent 工作流、CI 管道写着if (code ERR_UNKNOWN_COMPONENT)删掉或改义一个码就等于给所有消费方发了一次破坏性变更。而error文字随时可变因为从来没人依赖它。更妙的是这个承诺不是靠自觉而是物理性地冻结的整个码表用Object.freeze封死见 error-codes.mjs任何试图在运行时篡改的尝试都会直接抛错。命名规范一眼看懂错误属于谁所有错误码遵循统一格式ERR_主题[_限定词]按主题分组。看几个真实例子就能感受到这种可读性ERR_UNKNOWN_COMPONENT— 组件名没找到ERR_AMBIGUOUS_TEMPLATE— 模板名命中了多个候选ERR_NODE_VERSION— Node 版本低于支持下限ERR_PATH_TRAVERSAL— 路径越权写入被安全机制拦截ERR_UNKNOWN— 万能兜底保证任何失败都带码命名即分类看到ERR_UNKNOWN_xxx就知道是查无此物看到ERR_AMBIGUOUS_xxx就知道该加过滤条件。对新手和 AI 来说猜出含义的门槛极低——这正是一个agent-ready设计系统应有的素养。测试是守护者契约由机器验证这套承诺由自动化测试层层把守error-codes.test.mjs单元层校验每个码都是非空、唯一、符合ERR_前缀规范的大写蛇形字符串并验证码表确实被冻结、不可新增篡改端到端层真实拉起 CLI 子进程触发查无组件错误选项缺少参数等典型失败路径断言返回信封里的code与预期精确一致。换句话说错误码永不变不是一句口号而是每次提交都会被验证的硬约束。对初学者的启示Astryx 这个小小的设计决策其实给出了通用的 API 稳定性清单机器契约与人类文案分离——程序分支用稳定标识符文字只服务阅读体验稳定标识符只增不改——把向后兼容从代码审查习惯升级为不可违反的规则用冻结对象和契约测试固化承诺——让规则不依赖人的记忆命名即文档——让错误码本身自解释。这套规范完整记录在 cli-surface.md架构不变量与 cli-conventions.md贡献指南完整错误码清单则自动同步生成在 packages/cli/README.md 中。理解了这个 Append-only 稳定标识符的设计你写出的任何程序化消费逻辑都可以真正安心分支了。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Astryx错误码设计哲学：Append-only稳定标识符让程序可以安心分支
Astryx错误码设计哲学Append-only稳定标识符让程序可以安心分支【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个开源设计系统内置一套专为 AI Agent 和 CI 脚本设计的 CLI 工具。它最巧妙的细节之一是错误码的设计哲学采用Append-only只追加的稳定错误码标识符让程序可以放心地对错误做分支判断而不用害怕明天升级后逻辑就悄悄失效。为什么错误码比错误信息更重要传统命令行工具失败时会打印一句人类可读的报错比如找不到组件 Button。人看着没问题但程序怎么办只能去匹配文字。一旦某天官方把这句话改写成别的措辞、或者翻译成了别的语言你的脚本就静默断裂了——这是所有基于字符串匹配的错误处理最大的隐患。Astryx 的 CLI 把给程序看和给人看彻底分开了。它的目标调用者就是 AgentAgent 在子进程里运行 CLI读取 JSON 输出然后无人值守地决定下一步动作架构依据见 cli-surface.md。JSON 信封机器友好的统一输出Astryx CLI 加--json参数后所有输出都收敛为两种固定信封格式实现在 json.mjs成功{ apiVersion, type, data }可附meta失败{ apiVersion, error, code }可附suggestions关键点在于失败信封里有两个字段分工明确字段给谁看能否变error人类随时可以改措辞、本地化code程序永不变一旦发布就冻结架构文档把它写成了正式不变量INV3——代码即契约文字不是消费方只对code分支永远不要对error字符串做匹配。Append-only只追加不改写不删除Append-only 是这套设计哲学的核心用一句大白话说就是错误码表是一张只允许往后加新条目的清单。✅ 可以新增遇到新的失败场景追加一个ERR_开头的新码❌ 不可以改义已发布错误码的含义永远不变❌ 不可以删除哪怕某个场景不存在了码也保留为什么这么固执因为每个错误码都是一次对外的承诺。下游可能有几百个 Agent 工作流、CI 管道写着if (code ERR_UNKNOWN_COMPONENT)删掉或改义一个码就等于给所有消费方发了一次破坏性变更。而error文字随时可变因为从来没人依赖它。更妙的是这个承诺不是靠自觉而是物理性地冻结的整个码表用Object.freeze封死见 error-codes.mjs任何试图在运行时篡改的尝试都会直接抛错。命名规范一眼看懂错误属于谁所有错误码遵循统一格式ERR_主题[_限定词]按主题分组。看几个真实例子就能感受到这种可读性ERR_UNKNOWN_COMPONENT— 组件名没找到ERR_AMBIGUOUS_TEMPLATE— 模板名命中了多个候选ERR_NODE_VERSION— Node 版本低于支持下限ERR_PATH_TRAVERSAL— 路径越权写入被安全机制拦截ERR_UNKNOWN— 万能兜底保证任何失败都带码命名即分类看到ERR_UNKNOWN_xxx就知道是查无此物看到ERR_AMBIGUOUS_xxx就知道该加过滤条件。对新手和 AI 来说猜出含义的门槛极低——这正是一个agent-ready设计系统应有的素养。测试是守护者契约由机器验证这套承诺由自动化测试层层把守error-codes.test.mjs单元层校验每个码都是非空、唯一、符合ERR_前缀规范的大写蛇形字符串并验证码表确实被冻结、不可新增篡改端到端层真实拉起 CLI 子进程触发查无组件错误选项缺少参数等典型失败路径断言返回信封里的code与预期精确一致。换句话说错误码永不变不是一句口号而是每次提交都会被验证的硬约束。对初学者的启示Astryx 这个小小的设计决策其实给出了通用的 API 稳定性清单机器契约与人类文案分离——程序分支用稳定标识符文字只服务阅读体验稳定标识符只增不改——把向后兼容从代码审查习惯升级为不可违反的规则用冻结对象和契约测试固化承诺——让规则不依赖人的记忆命名即文档——让错误码本身自解释。这套规范完整记录在 cli-surface.md架构不变量与 cli-conventions.md贡献指南完整错误码清单则自动同步生成在 packages/cli/README.md 中。理解了这个 Append-only 稳定标识符的设计你写出的任何程序化消费逻辑都可以真正安心分支了。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考