维护文档与示例

根 README 负责认识项目与最小体验，docs/ 负责学习、查询和设计解释，包 README 提供模块内部阅读材料。文档网站应从同一套 docs 内容发布，不另维护一份人工改写的正文。

内容放在哪里

读者目的	位置	应包含的内容
第一次完成操作	getting-started/	最小完整步骤、前提、可观察结果
完成具体任务	cookbook/	独立配方和必要分支，链接准确规则
理解为什么这样设计	design/	问题、概念、职责、具体流程与取舍
查询精确契约	reference/	字段、默认值、公开接口、状态与生命周期
修改项目	contributing/	源码入口、扩展选择、验证和工作约定
系统介绍项目	project-tour.md	组织讲解的路线，复用已有专题

设计页不需要复制每个函数签名，Cookbook 也不必重复整张参数表。正文应独立可读，再把需要深入的读者引到真实源码。

行为改变时更新哪些页

• 配置字段、默认值或路径改变：先更新对应参考，再核对包含它的入门和配方。
• 公开 SDK 变化：同步完整代码块、示例命令与返回值说明。
• 生命周期或职责改变：检查设计流程图、相关指南和贡献者地图。
• 新增能力：增加有实际内容的入口，必要时更新 docs 首页；只有影响项目定位或最小路径时才改根 README。

从现有类型、schema、实现和测试查事实。旧 README、历史设计文档或目录名可以帮助定位，但不能证明当前行为。公开材料不要保留本机绝对路径、私有工作笔记链接或尚不存在的页面。

安装、运行和测试示例使用标准命令。个人开发机的缓存目录、权限绕行和临时执行参数不写入通用步骤；只有产品本身存在平台差异时，才分别说明。

如何检查和预览

正文仍以普通 Markdown 保存，可以在仓库页面或 Markdown 编辑器阅读。网站工程在 iris-web 维护，使用 VitePress 渲染同一套内容；本地预览命令见该仓库 README。开发预览可以读取当前工作区，线上文档只随正式版本更新。

检查每个变化页面的内部链接、锚点、代码块语言和推荐下一步。完整 Python/YAML 例子应在写明的工作目录和前提下验证；仅解释接口的片段应明确标为片段，不把省略部分的代码称为可直接运行。

参数和正文变化通常不需要全量项目测试。改了可运行示例就检查对应路径；依赖模型、Docker 或外部服务而未实际执行的部分，在交付记录中说明范围。

维护网站内容

页面之间使用相对 Markdown 链接；正文中的源码链接指向仓库路径。网站集成需要分别映射这两类链接，核对 .md 路由、锚点、图片和部署子路径；不能假定 ../../src/iris/... 是网站里的文档页面。

导航以docs 首页的阅读路线为基础，在 docs/navigation.json 维护分组和顺序。每个条目的 path 相对 docs 目录；新增、重命名或移除页面时，在同一个变更中更新导航与引用。

首页复用快速开始中由 iris-web:install、iris-web:minimal-agent 和 iris-web:run HTML 注释标出的代码块；这些注释不影响 Markdown 阅读。修改示例时保留成对标记，不在网站中再改一份命令。安装命令统一使用 git clone https://github.com/Tsubaki-01/Iris.git，从仓库默认分支获取源码。

正式 Release 发布后通知 iris-web，网站检出 GitHub latest 正式版本，构建正文、导航、图片和搜索索引。“查看本版源码”对应构建使用的提交；“编辑此页”指向维护分支，修改随后续版本发布。普通文档合并和预发布不会更新线上正式文档。同版本文档勘误可从对应 Release 标签创建修订提交，由 iris-web 的 .github/docs-revisions.json 指定该提交并重建，保持版本号。

主题、页面样式、链接转换与构建脚本在 iris-web 维护。生成的网页与文档副本不回写本仓库；重新部署当前正式版本可在 iris-web 手动运行部署工作流。