|
|
c151d391ee
|
docs(release): §四 补客户端版本必须与内核同步 + make 门禁
|
2026-09-15 11:04:31 +08:00 |
|
|
|
180b96e21a
|
docs: 记下 gitcode 附件的"同名只写一次"硬约束（校验和首次没传全就永远补不回来）
实测证据：同一个名字（ZZprobe.txt）传两次不同内容，下载端始终返回第一次那份；
资产列表里该名字只有一项。删除接口走不通 —— release JSON 不含 `id`，附件列表接口 404，
`DELETE .../releases/<tag>/attach_files/<name>` 返回 400「参数类型错误」（要数字 id）。
后果（1.3.1–1.3.10 全都踩了）：首次上传 `SHA256SUMS` 时只有 linux/amd64 四个产物，
之后补 arm64/darwin/win 时"合并后重传"**全部无效** —— 线上那份至今仍是 4 项、带 `./` 前缀，
arm64/darwin/win 的产物没有校验依据。
⇒ 纪律：**打包全部平台后才第一次上传校验和**；分批上传时先传产物、最后传校验和，
校验和只传一次。补救只能换名（`SHA256SUMS.complete`）或重建 release（需重传全部产物）。
|
2026-09-13 18:50:06 +08:00 |
|
|
|
8910c8c454
|
docs: 补两条流水线纪律（脚本必须 set -e；tag worktree 里的驱动脚本）
今天连踩两次，都是"脚本本身"的问题而不是打包逻辑的问题：
1. **没 `set -e`**：`package-windows.sh` 在 tag worktree 里找不到（新脚本只在 main），
bash 报 No such file or directory 之后**流程照旧往下走**，把只含 4 项的校验和
传上去覆盖了原本覆盖 10 项的那份 ⇒ 只能把产物下回来重建。
2. **驱动脚本不在 tag 里**：发布件在 tag 的干净 worktree 里构建，而刚补的脚本还没进 tag。
⇒ 让脚本支持 `DIST_LINUX` / `BUILD_DIR` / `DIST_RELEASE` 覆盖，用"主仓脚本 + 产物目录
指向 worktree"来解；文档写清这条约束。
同步进发布技能的同名小节（这两条和"分批上传要全量重算校验和"是同一类：**校验和的完整性
比产物本身更容易被流程吃掉**）。
|
2026-09-13 18:23:22 +08:00 |
|
|
|
594496a225
|
feat(packaging): 补 Windows(WSL) 安装器的驱动脚本，并按变体定向 payload
用户要求：**Windows 的 homed 安装包应当是往 WSL 里安装**。口径本身早已落地
（installer.nsi 注释 + install-via-wsl.ps1 + build.sh 的 WSL 分支），但缺两样东西：
1. **没有驱动脚本**：`build.sh` 里没有 `makensis`，仓库里也没有任何脚本调用它 ——
build/ 下那几个历史 .exe 是手工打的。新增 `deploy/packaging/package-windows.sh
<server|client|full> [arch]`：按变体准备 payload、必要时编 waiter.exe、调 makensis、
把产物落到 dist/release。
2. **payload 不分变体**：`build.sh` 的 `stage_linux_payload` 把 dist/linux 下所有 deb+tar
全塞进 payload ⇒ 现在 server/full 的 deb 各带 ~719MB 模型，任何变体的安装器都会
膨胀到 ~2.4GB。而 WSL 侧脚本只取 payload 里的**第一个** `.deb`
（install-via-wsl.ps1:141）⇒ 按变体只放对应的那一个包。
同时：client/full 需要 Windows GUI payload（HAS_GUI=1），本机无 electron-builder 时
**明确失败并给出命令**，不产出"装完没有界面"的半残包。
docs/git-branching.md §七.5 补上这条口径与三条命令。
|
2026-09-13 18:13:04 +08:00 |
|
|
|
56ba1332f3
|
docs: 补「分批上传时后一轮必须全量重算 SHA256SUMS」
实测踩到：v1.3.10 先传 amd64 的 9 个资产（含只覆盖 amd64 的 SHA256SUMS），
后补 arm64 时按 arm64 那 4 个文件重算 ⇒ 同名附件覆盖 ⇒ amd64 的校验和消失。
校验和是附件的唯一完整性依据，丢了等于没有校验。已同步到技能的同名小节。
|
2026-09-13 17:35:02 +08:00 |
|
|
|
fb2db2c304
|
docs: 两仓文档对齐当前版本状态 + 补发版产物清单；同步 SDK meta 路牌
用户指出：SDK 版本又带 patch 位、agent 自称 1.0.3、两个仓库文档都没更新。
docs/git-branching.md：
1. **§三 状态表**重写（停在 2026-09-12：main 还写 1.3.0、release/v1.2.x 还被当成"本条发布线、
尚无 tag"、SDK main 还写 1.2.0、完全没有 release/v1.3.x）。现按事实更新，并写明
`v1.3.0` 是已撤回的坏 tag。
2. **§2.3** 增补：发布线的 `meta.Version` 必须跟着该线已发的最后一个 patch 走；
只用 `-ldflags -X` 打版本而不改源码会让二进制与源码对不上账（1.3.1–1.3.4 就是这么打的）。
3. **反例表**补两行：人格文本在**播种时**固化版本（生产实例自称 v1.0.3）、
发布线路牌不随 patch 推进 / 给 SDK 误发 patch tag。并澄清"插值"必须在**渲染时**，
把算好的结果固化进配置库与写死没有区别。
4. **§七.5 新增"发版产物清单（可复现）"**：核心仓（tar.gz + 3 个 deb + SHA256SUMS，
校验和必须在全部产物生成后统一算）、SDK 仓（5 平台 hmapdev + SHA256SUMS）、
上传脚本的用法与两个坑（release 条目必须先存在；`hmapdev_*` 无扩展名不会被自动识别）。
起因就是本次"推了 tag 却没建 release、没打包"——推 tag ≠ 完成发版。
third_party/homeagent-sdk/meta/meta.go：镜像 SDK 仓 main 的路牌（1.3.0 → 1.4.0）与
版本语义注释更新（1.3.0 已定版 ⇒ 该号归发布线，main 推进）。
|
2026-09-13 14:41:24 +08:00 |
|
|
|
ea21803acb
|
docs(branching): 明确开发者文档的发布归属——以 rel 分支的形态为准，再合入 main
用户裁定：开发者文档应当在每个 rel 分支被修正为对应 rel 的形式，随后合入 main。
新增 §二.7，写清：
- 规则与做法（release 上按本版口径改 → cherry-pick 到 main，遵守 §三 只 pick 不 merge）
- 为什么不能直接改 main：main 语义是「下一个未发布版本」；assets/docs 会随发行包
分发并在 WebUI 被阅读，服务的是「这一版」；版本号/工具名/机制有无都随版变动
- main 上描述「下一版才有」的行为必须显式标注（如「（下一版）」）
- 反例表（本仓真实踩过）：人格卡写死 v0.9.0 + 已删除的 C ABI、架构文档把已移除的
描述式索引/引用计数写成现行、README 停在旧版本
- 配套硬约束：任何会被当作事实的文本不得写死版本号，须插值或读运行时快照并加测试
|
2026-09-12 13:05:24 +08:00 |
|
|
|
727768e083
|
docs(git): 修正上一提交的错字（但声两仓 → 但两仓）
|
2026-09-12 09:01:59 +08:00 |
|
|
|
0247206dfe
|
docs(git): 写清「两仓 main 同步推进」的前提，修正 SDK 路牌
§七.4 原来只说「在 1.1.x 线发布期间，两仓 main 上的值都是 1.2.0」，容易被读成
「两仓 main 永远同值」，我正是据此把 SDK main 也推到了 1.3.0（已回退为 1.2.0）。
补写前提：推进以**该中版本已正式发布**为条件。
- 核心切出 release/v1.2.x 后 1.2.0 归发布线所有 → main 立即到 1.3.0（beta 也算占号）
- SDK 因 §七.2（beta 不发 SDK）要等核心正式 tag 才定版 → 在那之前 main 停在 1.2.0
并明确：**此阶段核心 main(1.3.0) 与 SDK main(1.2.0) 故意不对称**，
不是遗漏同步。§三 的 SDK 表行同步修正。
|
2026-09-12 09:01:34 +08:00 |
|
|
|
f778c613f1
|
docs(git): 1.2.x tag 历史补上 v1.2.0-beta.1
release/v1.2.x 已按 §2.4 走出 beta 通道：tag v1.2.0-beta.1（提交 215804c），
注释里写明通道、不兼容点与验收证据；beta 阶段不发 SDK（§七.2）。
正式 tag 待试运行无回退问题后再打，届时同步 SDK 仓。
同时把 tag 名资产整理记录在案：历史大写 tag V0.8.0 / V0.7.1 已按用户确认删除
（提交本身未受影响），现在主仓 tag 全部符合 SemVer 小写 v 约定。
|
2026-09-12 08:54:09 +08:00 |
|
|
|
a070cb563d
|
docs(git): 分支对齐更新到 2026-09-12（1.2.x 线开启）
- main 路牌调到 1.3.0；release/v1.2.x 承载 1.2.0（vendored SDK 定版 1.2.0）
- release/v1.1.x 按 §2.6 退役（保留供追溯）；两个历史 feature 分支
（memory-media / plugin-proc-migration）已从远端删除，旧表待删项清掉
- 新增「1.2.x 发布线 tag 历史」表（当前尚无 tag），并写明它与存量插件
**不兼容**（RPC 协议 2、fd3 布局改变、不支持滚动升级）以及
**不满足 §2.4 跳级条件**的理由（改动面大，非单点修复）
- SDK 仓的 release/v1.2.x 尚未创建：按 §七.3 随核心**正式** tag 一起做
|
2026-09-12 08:39:05 +08:00 |
|
|
|
8c6b593a54
|
docs(git): SDK 仓版本语义与发版联动，并明确 main 永不作发版分支
三条此前没写进规范、于是被我在实际操作中做错的规则：
## 一、SDK 版本号跟随核心的中版本，patch 位恒为 .0（新 §七.1）
整条核心 1.1.x 线共用 SDK 1.1.0；只有核心进入 1.2.0 这种中版本跃迁时 SDK 才升。
核心的 patch 位专用于 bugfix 与漏洞修复，这类改动不碰公开 SDK 接口，SDK 版本号
没有理由跟着动。
**为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix
就给 SDK 推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个
字都没变。让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在
为哪个中版本写插件」。
因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0），
不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。§四 的措辞同步修正。
## 二、beta 阶段不发 SDK（新 §七.2）
核心的 alpha/beta tag 不伴随 SDK 仓发版：SDK 仓在这一阶段不打 tag、不建 release。
**为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版，
插件开发者会照着一个还会变的接口写代码——那是无效开发。接口没定就没有可依赖的
契约，发出去的版本号是一个假承诺。
这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。主仓用
`replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored SDK 源码，
那是构建机制决定的，不在约束范围内。
核心打**正式** tag 时 SDK 才随之发版（§七.3）：SDK 仓也有自己的 `release/vX.Y.x`，
定版为 `X.Y.0`，打 tag、建 release、传 5 平台 plugindev 产物。同一中版本内的后续
核心 patch 不重复发 SDK。
## 三、main 永远不是发版分支（补进 §四）
版本号 bump、打 tag、构建产物、上传附件，全部只在 `release/vX.Y.x` 上做。
**即使某个改动刚合进 main、即使 main 此刻可部署，也不从 main 打 tag。**
main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。
这条本该是 §2.1「main 的 meta.Version 始终是下一个未发布版本」的直接推论，但
只写了状态、没写禁令，于是留下了「main 可部署 ⇒ 可以从 main 发版」的误读空间。
§三 的分支表补上 main 现值 `1.2.0` 与 1.1.x 线的 tag 历史，让路牌语义有实例可对。
## 四、公开接口改动是 feature，不是发布准备（补进 §六）
它必须走 `feature/xxx` → 合回 main → cherry-pick 到发布分支，不允许当成「发布
分支上的 bug 修复」直接提交进 release——发布分支冻结功能（§2.3），而接口是最
典型的功能面。§五 补上这条路径的命令示例，以及 SDK 仓同步发版的命令。
|
2026-09-06 09:52:52 +08:00 |
|
|
|
e2d04a31a7
|
docs(git): 发布分支改为一个中版本一条，补三级发布通道规范
## 一个中版本一条发布分支
原规范写 release/vX.Y.Z（含 patch 位），实践中 1.0.0 与 1.0.1 各建了一条
分支，导致同一条 1.0.x 发布线被切成互不相连的碎片——追溯时无法用一条
分支看完整条线的演进。改为 release/vX.Y.x，patch 位用 x 占位，
承载该中版本全部 patch 直到下一条中版本分支切出。
## 三级发布通道（alpha / beta / 正式）
通道由 tag 区分而非分支：三者共用同一条 release/vX.Y.x。
alpha vX.Y.Z-alpha.N 功能齐了未充分验证 仅内部自测
beta vX.Y.Z-beta.N alpha 问题已修 小范围试用
正式 vX.Y.Z 通过验证可上现网 所有用户
这是 semver 标准预发布语义（1.1.0-alpha.1 < 1.1.0-beta.1 < 1.1.0），
版本比较逻辑天然认得，无需额外约定。允许跳级但要在发布说明写明理由；
alpha/beta 产物不上现网——预发布通道的存在就是为了不拿 24/7 服务冒险。
## 回流仍是 cherry-pick
明确不改 merge：merge 会把已发布的版本号带进 main，与「main 的
meta.Version 始终是下一个未发布版本」直接矛盾。
新补一条：修复落地当天要 pick 到所有活跃 feature 分支，否则它们合回
main 时可能带回旧代码（2026-09-04 的 stage 双重解锁修复即同时 pick 到
main 与 feature/memory-media）。
## 运维纪律沉淀
把今天走通的部署流程写进第四节，其中两条是踩过的坑：
- 备份配置库用 sqlite3 .backup 而非 cp（WAL 模式下 cp 可能拿到
不一致快照）
- install -m 0755 替换而非 cp（原子 rename，不写坏运行中的进程镜像）
健康检查列出六项，含「一次真实对话」与「fatal error 计数为 0」。
## 当前分支对齐
第三节更新为 2026-09-04 的实际状态，并记录 1.0.x 的 tag 历史表
（含 v1.0.2 未使用的原因、v1.0.3 直接跳正式 tag 的理由）。
按 patch 号命名的历史发布分支标注为应当删除的遗留形态。
|
2026-09-04 20:11:19 +08:00 |
|
|
|
fe2fdc9692
|
docs: 固化当前分支对齐记录（update→feature/plugin-proc-migration）
|
2026-08-31 12:37:43 +08:00 |
|
|
|
69a138c1af
|
docs: Git 分支管理规范（main 长命 + feature/release/hotfix cherry-pick 流程)
- main 唯一长命、永远可部署；现网永远部署 release tag 构建
- feature/xxx 从 main 开出合回；release/vX.Y.Z 切出打 tag 构建
- hotfix 提交 release 分支 + 版本号分离提交，只 cherry-pick 修复回 main
- 明确'不需合并 release 回 main'（hotfix 已逐个 pick 回，避免冲突）
- 两仓（TrueAgent + homeagent-sdk）同用本规范
|
2026-08-31 12:36:44 +08:00 |
|
