docs(release): separate development pushes from releases

AGENTS.md

@@ -36,8 +36,11 @@
 
 ## 文档与版本
 
-- 版本号、`CHANGELOG.md`、`PROGRESS.md` 在 push 前统一更新一次，不按每个 commit 更新。
-- push 前更新 `PROGRESS.md`：补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。
+- 开发 push 与正式发布分离：功能开发期间允许持续 commit / push，不因此提升版本号，也不新增已发布的 `CHANGELOG.md` 数字版本条目。
+- 尚未发布但需要预先整理的用户文案写在 `CHANGELOG.md` 顶部 `## Unreleased`；该区不会被前端更新日志接口解析。正式发布时再把它改成 `## <版本> — <日期>`。
+- 版本号与用户版 `CHANGELOG.md` 只在功能稳定、准备上线时通过单独的 release commit 统一更新；同一次发布中校准 `PROGRESS.md`，不按每个开发 commit 更新。
+- 阶段性成果可随开发更新 `PROGRESS.md`；正式发布前补“已完成关键能力”条目，状态表变化随之更新，新增或删除模块时同步文件清单。
+- 未完成且不能让线上用户接触的功能，应在独立功能分支开发、待稳定后合并生产分支；若必须提前合并或部署，则使用默认关闭的 feature flag，并限制为管理员或测试账号启用。
 - 版本号唯一事实源是 `core/__init__.py::__version__`：
   - patch：bug 修复、重构、调参、新 skill、样式；
   - minor：成批新功能或明显对外行为变化；
@@ -59,4 +62,3 @@
 ## 领域语境
 
 主要使用方是中国建筑材料科学研究总院，核心语境是无机非金属材料研发与生产，包括水泥、混凝土、玻璃、陶瓷、耐火材料和新型建材。典型任务是配方研发、性能测试、XRD/SEM/热分析、实验数据建模，以及申报书、调研报告、专利和论文写作。默认按材料研发而非建筑施工、结构计算或 BIM 理解需求。
-

CHANGELOG.md

@@ -3,7 +3,13 @@
 > 面向用户的更新说明,由 `GET /v1/changelog` 解析后在前端「点版本号」弹层展示。
 > 维护口径:只记**用户可感知**的变化("能干什么了"而不是"改了哪个模块"),纯内部重构 / 修复不记,
 > 所以不是每个版本号都有条目。条目格式 `## <版本> — <日期>`,新条目加在最上面。
+> 开发中的用户文案可先写入 `## Unreleased`；该区不会被前端解析，正式发布时再替换为数字版本和日期。
 > 工程口径的完整记录见 `PROGRESS.md` / git log。
+
+## Unreleased
+
+<!-- 在这里整理尚未发布的用户可感知变化；功能稳定后随 release commit 填入版本号和日期。 -->
+
 ## 0.65.2 — 2026-08-13
 
 - 粘贴、拖拽或选择附件发送后，对话中的用户消息会保留附件卡片；图片同时显示可点击放大的缩略图，刷新历史对话后也不会消失。

RUN.md

@@ -538,6 +538,18 @@ sudo bash deploy/update_bluegreen.sh
 > 蓝绿部署机(生产,已 bootstrap)一律用 `sudo bash deploy/update_bluegreen.sh`(见上节)。
 > 下面的 `update.sh` 是单实例版:host backend 机 / 内网机 / 未切蓝绿的部署继续用。
 
+开发 push 与正式发布是两个动作：开发期间可以持续 push，但不提升
+`core/__init__.py::__version__`，也不新增 `CHANGELOG.md` 的数字版本条目。需要提前整理的
+用户文案写在 `## Unreleased`，前端不会展示。功能稳定后创建单独的 release commit，统一完成：
+
+1. 将 `## Unreleased` 改为 `## <版本> — <日期>`，只保留用户可感知的变化；
+2. 更新 `core/__init__.py::__version__`；
+3. 校准 `PROGRESS.md`，并按变更类型同步本文件或 `DESIGN.md`；
+4. 部署并验证 `/healthz` 与 `/v1/changelog`。
+
+未完成且不能向线上用户开放的功能应留在功能分支，稳定后再合并生产分支；必须提前部署时，
+使用默认关闭且仅向管理员或测试账号开放的 feature flag。
+
 **一把梭(单实例):`deploy/update.sh`**
 
 ```bash

tests/test_changelog.py

@@ -8,6 +8,10 @@ SAMPLE = """# 更新日志
 
 > 导语在首个条目前,应被丢弃。
 
+## Unreleased
+
+- 尚未发布,不能出现在用户版接口中
+
 ## 0.55.0 — 2026-07-09
 
 - 条目 A
@@ -36,6 +40,12 @@ class ChangelogParseTests(unittest.TestCase):
     def test_preamble_before_first_entry_is_dropped(self) -> None:
         es = _parse_changelog(SAMPLE)
         self.assertNotIn("导语", es[0]["body_md"])
+        self.assertNotIn("尚未发布", es[0]["body_md"])
+
+    def test_unreleased_section_is_not_returned(self) -> None:
+        es = _parse_changelog(SAMPLE)
+        self.assertNotIn("Unreleased", [e["version"] for e in es])
+        self.assertEqual([e["version"] for e in es], ["0.55.0", "0.54.1", "0.53.0"])
 
     def test_real_changelog_file_parses(self) -> None:
         # 仓库里的真文件:格式坏了(条目头打错 / 空正文)在 CI 就翻车,不等用户点开才发现