Streamlit 规格文档体系产品 Spec 与技术 Spec 的编写流程与仓库实践【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit本指南围绕 Streamlit 开源仓库中的 specs 目录 展开系统讲解 Streamlit 团队如何通过product-spec.md与tech-spec.md两类规格文档完成新功能的立项、评审与落地。读完本文你将掌握 Streamlit 规格文档的触发条件、模板结构、编写流程与审查门槛并能参照仓库内数十个真实 Spec 案例如分页组件、骨架屏、并行 Fragment 等学会撰写一份高质量、可评审、可被实现直接引用的技术规格。规格文档体系一个目录、两类文档、一套流程在 Streamlit 仓库根目录下specs 目录集中存放所有产品与技术规格文档。按照 specs/README.md 的定位说明该目录仅限内部使用Only for internal use so far但其中沉淀的写作规范、决策记录与 API 设计原则对任何希望为 Streamlit 贡献新特性的开发者都有直接参考价值。目录的组织方式是每个特性一个子目录子目录以日期加特性名命名例如2026-03-22-st-pagination/目录内可包含product-spec.md、tech-spec.md以及与该特性相关的设计稿、示意图等附加素材。截至当前仓库specs 下已积累了 40 余个真实特性规格覆盖分页组件、Mermaid 图表、骨架屏、并行 Fragment、动态 Tabs/Expander/Popover、st.context.theme.type语义修正、数据导出禁用等横跨前端渲染、后端运行时常量、状态管理与 API 设计的多类主题。同一个特性目录允许同时包含product-spec.md和tech-spec.md——当特性同时需要做什么/为什么与怎么做的双重对齐时例如 2026-08-08-st-context-theme-type 目录同时引用了两份文档两个文档分工协作、互相引用。什么时候需要写规格文档specs/README.md 对何时需要写 spec给出了清晰的判定标准specs/AGENTS.md 又对其进行了补充总结。两者的共识是并非所有改动都需要规格文档。不需要写 Spec 的情况以下三类改动无需规格文档Bug 修复Bug fixesDevOps 相关的改进DevOps-related improvements小规模、无争议的用户可见增强Small, non-controversial user-facing enhancements这类改动影响面小、方向明确直接走常规 PR 流程即可为它们撰写完整规格反而会拖慢交付节奏。需要写 Product Spec 的情况当满足以下任一条件时应撰写product spec产品规格提议一个新的用户可见特性user-facing feature或重大 API 变更在实现开始之前需要就**做什么thewhat与为什么thewhy**达成一致需要设计原型design mockups或 UX 决策的签字确认sign-off。需要写 Tech Spec 的情况当满足以下任一条件时应撰写tech spec技术规格特性不面向用户但具有架构意义architecturally significant在实现开始前需要就**怎么做thehow**达成一致例如 proto 设计、状态管理方案、前后端拆分frontend/backend split存在多条实现路径且各路径间有值得记录的实质性权衡meaningful trade-offs。判定本质_what_/_why_归产品_how_归技术规格文档的核心价值在于在代码动工之前完成认知对齐。product spec 回答给用户解决什么问题、API 长什么样tech spec 回答内部架构怎么搭、proto 怎么改、状态怎么管。当一个特性同时牵涉用户感知与架构复杂度时两份文档并存于同一目录是规范做法。Product Spec 与 Tech Spec 的分工对比specs/README.md 用两句话精炼定义了两类文档的边界维度product-spec.mdtech-spec.md关注焦点What 与 WhyHow覆盖内容用户面临的问题、提议的 API、设计原型、行为描述内部架构、proto 变更、前后端设计、状态管理、备选方案典型触发场景新用户特性、重大 API 变更、UX 决策非用户可见但架构重要的改动、多实现路径需要权衡目录命名与 PR 流程与 tech spec 完全一致与 product spec 完全一致两类文档共享相同的目录命名约定与 PR 审查流程仅内容视角不同。仓库中的真实案例可以直观印证这一分工2025-12-03-dataframe-disable-export/product-spec.md 是典型的 product spec——它围绕如何禁用st.dataframe的数据导出CSV 下载与剪贴板复制展开给出了配置项client.disableDataExport的 TOML/命令行/编程式三种设置方式、行为清单、示例与备选方案2026-08-08-st-context-theme-type 则同时包含 product 与 tech 两份文档其中 product spec 明确写出本产品规格负责决定type的含义而协议细节、后端解析与 MPA 安全的自动重跑设计则交由 tech spec 承载。创建一份 Spec 的完整流程specs/README.md 给出了从建目录到合并的 5 步标准流程这是本文最需要原样继承的操作手册部分复制模板目录将specs/YYYY-MM-DD-template/复制为一个以当前日期命名的新目录命名为specs/YYYY-MM-DD-my-feature-name/例如specs/2026-02-05-datetime-widget/。仓库中真实存在的是2026-03-22-st-pagination/、2026-05-13-st-skeleton/等按此约定的目录。填写文档在模板基础上填充 product-spec.md 或 tech-spec.md或两者都填。创建 PRPR 标题格式为[spec] My feature name例如[spec] Datetime widget在讨论就绪之前PR 应保持Draft草稿状态。开启评审内容就绪后将 PR 标记为 Ready for review所有关于该规格的讨论都应发生在 PR 上而非散落在 Issue 或群聊中。合并与后续通过至少需要两位核心维护者core maintainers批准。批准后维护者会添加change:spec标签、合并 PR并在相关 Issue 中链接该规格此时规格即被视为可实现ready for implementation拒绝PR 被关闭并附带说明。这一流程保证了规格文档不是写了就完事的存档而是经过社区评审、有明确状态草案中/评审中/已批准/已拒绝的活文档。模板结构详解一份合格 Spec 长什么样Product Spec 模板product-spec.md 以 YAML frontmatter 开头记录author: github-name与created: YYYY-MM-DD正文由五个章节构成Summary用 23 句话清晰简洁地描述该特性或增强Problem说明问题、动机或使用场景并链接所有相关的 GitHub Issue描述用户诉求Proposal提出解决方案模板建议的子章节包括——API命令名、参数、类型、默认值、Behavior含错误与边界情况、Design链接 Figma 文件和/或附上原型图或截图、Examples含代码片段Checklist一张必须逐项核对的表格模板预置了以下检查项Item✅ or commentWorks on SiS, Cloud, etc?No breaking API changesNo new dependenciesMetrics collectedAny security/legal impact?Any docs changes needed?真实案例中这张表会被认真填写而非留白。例如 2025-12-03-dataframe-disable-export/product-spec.md 的 checklist 逐项标注了✅ 兼容 SiS/Cloud✅ 无破坏性 API 变更✅ 非安全特性仅作为便利功能文档化等结论2026-05-13-st-skeleton/product-spec.md 则标注了纯前端动画、无服务器依赖新增skeleton指标、内部_skeleton保持独立等细节。Tech Spec 模板tech-spec.md 结构更轻包含四个章节Summary概述该技术规格覆盖的内容Problem描述被解决的技术问题或限制链接相关 Issue 与先前实践prior artProposal描述提议的技术解决方案Alternatives Considered评估过的其他方案及被否决的原因。模板之外的可选章节仓库中的真实 Spec 在模板基础上演化出了大量实用章节可以直接借鉴Edge Cases边界情况表格——2026-03-22-st-pagination/product-spec.md 用一张表穷举了num_pages 1、num_pages 1、max_visible_pages 0/1/2/None、num_pages运行时缩小等场景及各自行为Out of Scope未来工作——多数 Spec 都会明确列出本次不做、留待后续的项。例如 pagination spec 列出了自定义标签、跳转输入框、每页条数选择器等skeleton spec 列出了形状变体shapecircle、多行骨架lines3、动画定制等行为矩阵Behavior Matrix——2026-08-08-st-context-theme-type/product-spec.md 用一张配置-期望结果矩阵展示了type在预设主题、单自定义主题、双主题、病态配置等 8 种场景下应返回的值Open Questions——该 Spec 还在文末列出了四个必须显式回答的签署门槛sign-off gates如实标注了0.6% 应用使用率 vs 实现成本这类开放决策。规格编写实战指南来自仓库的七条铁律specs/AGENTS.md 的 Spec Guidelines 一节沉淀了 Streamlit 团队多年编写规格的经验是 README 流程之外最值得学习的内容先问题后方案Problem First, Solution Second永远不要从想做什么开始写而是从**为什么why**开始——链接 GitHub Issue、展示具体的用户痛点与现有 workaround、包含使用场景。仓库中的每份 spec 都严格遵循此序先铺陈用户请求与痛点再进入 Proposal。给选项而不是下命令Present Options, Not Edicts对非平凡的 API给出 23 个选项并逐一列出优缺点用✅ PREFERRED标注倾向方案。典型例子是 pagination spec 中st.paginator包装器与底层st.pagination的对比以及 skeleton spec 中SkeletonPlaceholder包装类 vs 普通DeltaGeneratorvs 拆分两个命令三种返回类型方案的权衡。最小起步明确记录范围外Start Minimal, Document Out-of-Scope只交付最小可用 API并显式列出本次不包含什么。例如 skeleton spec 明确排除了形状变体、多行、动画定制、主题化、标签叠加等未来项。用代码说话Show Code, Not Just Words每个 API 都要有具体示例先展示最简单的用法再逐步增加复杂度。pagination spec 提供了基础用法、带回调、分页 DataFrame、多步向导、通过 session state 程序化跳页等由浅入深的五个完整示例。保持简洁Keep It Concise规格应覆盖最重要的方面而不冗余同一信息只解释一次后续引用而非重述。先参考既有 SpecReference Existing Specs动手前先研究specs/下已存在的规格匹配既有的风格与结构。评审者的时间宝贵让每一句话都有信息量。规格中的 API 设计原则为什么 Streamlit 的 API 长这样specs/AGENTS.md 的后半部分收录了Principles of Streamlit API Design共 36 条这是评审规格时被反复引用的底层准则也是理解仓库中众多 Spec 决策动机的钥匙。核心条目包括Simplicity First最常用场景应需要最少参数st.button(Click)应开箱即用Sensible Defaults每个可选参数都应有覆盖 80% 用例的默认值Start Minimal, Ship Fast参数永远只能增加难以删除sparkline_typebar可以以后再加Consistency Over Noveltyst.selectbox学会的用法应能迁移到st.radioStandardized Vocabulary统一使用label而非title、key而非id、help而非tooltip、on_change而非callbackPrefer Enums Over Booleans用Literal类型而非布尔值st.text_input(Password, typepassword)优于passwordTrue例外disabled永远只有两态Positional Arguments Are Precious仅 13 个最关键参数允许位置传参其余一律*分隔为 keyword-onlyOne Use Case, One Commandst.tabs只负责页内内容分页页面导航是st.navigation的职责Flat Namespace, Rare Submodules大部分命令保持在扁平的st.*命名空间只有st.components.v1、st.testing.v1、st.column_config等场景才使用子模块Fail Fast, Fail Helpfully立即校验参数并抛出清晰、可行动的异常Minimize Migration Distance新特性应尽量让老代码无痛升级加参数优于引入破坏性变更。这些原则在真实 Spec 中有大量回响。例如 2026-01-14-dynamic-tabs-expander/product-spec.md 为st.tabs/st.expander/st.popover引入的.open属性与on_changererun参数就明确引用了与图表/DataFrame 选区已建立的on_change模式保持一致的决策理由该 Spec 还详细比较了.open与.active/.selected/.visible/.state等备选命名最终因对 tabs/expander/popover 三种元素统一语义而选定.open——这正是 Consistency Over Novelty 与 Standardized Vocabulary 原则的现场演绎。从 Spec 到实现的闭环仓库源码佐证Spec 的价值最终要落到实现上。仓库源码可以验证多份已批准的 Spec 确实被实现并帮助读者理解 Spec 描述的 API 与底层实现的对应关系client.disableDataExportlib/streamlit/config.py 第 638 行注册了该配置选项lib/streamlit/runtime/app_session.py 第 1300 行在构建初始消息时将其读取并写入前端消息msg.disable_data_export config.get_option(...)lib/streamlit/elements/arrow.py 第 692 行附近的文档也明确指向该配置。这与 dataframe-disable-export Spec 中配置项默认false、控制 CSV 下载与剪贴板复制的描述完全吻合st.paginationlib/streamlit/elements/widgets/pagination.py 第 74 行实现了pagination函数对应 2026-03-22-st-pagination Spec 中返回当前选中页码、状态可跨重跑保持的 API 契约e2e 测试目录下存在配套的 st_pagination.py 与 st_pagination_test.pyst.skeletonlib/streamlit/elements/skeleton.py 第 65 行实现了skeleton命令lib/streamlit/delta_generator_singletons.py 第 166 行注册了SkeletonPlaceholder类对应 2026-05-13-st-skeleton Spec 中独立占位 上下文管理器双模式、默认高度为theme.sizes.minElementHeight2.5rem的设计。这类Spec 定义契约、源码兑现契约、e2e 测试守护契约的三层结构正是规格文档体系在仓库中真正发挥作用的体现。写在最后如何上手编写你自己的第一份 Spec综合 specs/README.md、specs/AGENTS.md 与仓库内数十份真实案例为 Streamlit 贡献一个新特性的规格文档可以遵循以下检查清单判定性质是小修复还是新特性是面向用户还是架构性改动需要 product spec、tech spec 还是两者创建目录复制specs/YYYY-MM-DD-template/以specs/YYYY-MM-DD-特性名/命名填充内容严格按模板章节展开先写 Problem附用户诉求与现状痛点再写 ProposalAPI 签名、行为、边界情况、完整示例并用 Checklist 逐项自检兼容性、依赖、指标、安全与文档影响备选方案认真记录 Alternatives Considered说明每条被否决路径的理由——这是评审者判断决策质量的关键依据明确范围用 Out of Scope 列出本次不做的事避免 API 过早膨胀创建 PR标题[spec] 特性名保持 Draft 直到内容就绪再请求两位核心维护者审批。规格文档是 Streamlit 这类大型开源项目中共识的载体——它让一次 API 设计决策可以被追溯、被讨论、被复用也让每一位贡献者在动笔写代码之前先想清楚 what、why 与 how。【免费下载链接】streamlitStreamlit — A faster way to build and share data apps.项目地址: https://gitcode.com/gh_mirrors/st/streamlit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考