jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-11-01 14:57:38 +00:00
Code Issues Packages Projects Releases Wiki Activity
889 Commits 5 Branches 29 Tags
49141fe6f061765b72eb3345f6052efe31bbad6d
Commit Graph

22 Commits

Author SHA1 Message Date
supervisor
a3ab6e5cfa docs(deploy): SDK 镜像仓示例统一为 hologramagentsdk 
upload_assets.py docstring 与 docs/git-branching.md 的上传示例里，SDK 仓
仍写 homeagent-sdk；按已定口径（SDK 仓名 hologramagentsdk，gitcode/GitHub
两侧均 200 实测）统一，避免与 sdk-docs 线合并后出现两种说法。

纯注释/文档改动，零代码逻辑变更。
 2026-10-21 20:18:30 +08:00
JianFeeeee
ee2b7d7bac fix(docs,site): 回退上一批错误口径 —— SDK 仓名与站点域名改回实际活链 
上一批（37b8c26 / 228fae2）把文档与站点里的 SDK 仓名统一改成了
`JianFeeeee/HologramAgent-sdk`、把站点域名改成了 `*.hologramagent.jianfgit.xyz`，
前提「本机无外网、无法验证」是错的。实测外网通畅，两处改动都是真实死链，本批全部回退。

## 一、SDK 仓名 HologramAgent-sdk → homeagentsdk（104 处）

| 文件 | 处数 |
|---|---|
| site/index.html | 23 |
| README.md | 7 |
| README_EN.md | 7 |
| assets/docs/zh/PLUGIN_DEV.md | 29 |
| assets/docs/en/PLUGIN_DEV.md | 29 |
| assets/docs/zh/OVERVIEW.md | 2 |
| assets/docs/en/OVERVIEW.md | 2 |
| docs/git-branching.md | 2 |
| docs/zh/ci-cd-runbook.md | 3 |
| **合计** | **104** |

含 `.git` 形态与 `cd homeagentsdk` 目录名。PLUGIN_DEV.md 里原本就是
`import "github.com/JianFeeeee/homeagentsdk/sdk"` 的两处示例（zh 253/448、en 255/455）
与 6a 前基线逐行 diff 无差异，未被改动成第三种形态。

## 二、站点域名 hologramagent.jianfgit.xyz → homeagent.jianfgit.xyz（15 处）

| 文件 | 处数 |
|---|---|
| README.md | 4 |
| README_EN.md | 4 |
| docs/zh/deploy-runbook.md | 2 |
| deploy/scripts/deploy-sdk-site.sh | 5 |
| **合计** | **15** |

deploy-sdk-site.sh 只改探活/注释里的域名，nginx 语义（SNI 透传、
server_name → root 的链路描述）未变。

## 三、明确未动

- go.mod 两行、third_party/homeagent-sdk 路径、internal/**/*.go 的 import —— 零改动
- deploy/scripts/upload_assets.py:23 默认值 `JianFeeeee/HologramAgent` 保留（主仓确已改名）
- cmd/gui/package.json homepage 保留 HologramAgent（GitHub 200）
- docs/git-branching.md:420 的 GITCODE_REPO 改为 `JianFeeeee/homeagent-sdk`：
  gitcode 上只有 homeagent-sdk(200) 与 HomeAgent(200)，HologramAgent-sdk 与
  HologramAgent 在 gitcode 均为 404

## 四、实测证据（curl -L -o /dev/null -m 25 -w '%{http_code}'）

GitHub 侧（经 http://127.0.0.1:7890 出口）：

    200  https://github.com/JianFeeeee/homeagentsdk          ← 回退目标，活链
    200  https://github.com/JianFeeeee/HologramAgent         ← 主仓，确已改名
    404  https://github.com/JianFeeeee/HologramAgent-sdk     ← 上一批写成这个，死链
    404  https://github.com/JianFeeeee/homeagent-sdk         ← 不是这个名字
    200  https://github.com/JianFeeeee/HomeAgent             ← 301 → HologramAgent

深链抽查（回退后全部 200）：

    200  .../homeagentsdk/tree/main/example/weather
    200  .../homeagentsdk/tree/main/example/plugindev
    200  .../homeagentsdk/tree/main/example/luademo
    200  .../homeagentsdk/blob/main/LICENSE
    200  .../homeagentsdk/tree/v1.1.0

站点域名（直连，不走代理）：

    200  https://sdk.homeagent.jianfgit.xyz/                ← 回退目标，已部署
    200  https://introduce.homeagent.jianfgit.xyz/
    200  https://sdk.homeagent.jianfgit.xyz/llms.txt
    200  https://sdk.homeagent.jianfgit.xyz/llms-full.txt
    404  https://sdk.hologramagent.jianfgit.xyz/            ← 上一批写成这个，未部署

新子域 404 的原因不是网络：证书是 CN=*.jianfgit.xyz 通配符可用，
但 nginx 里没有 hologramagent 的 server_name，站点根本没部署。

gitcode 侧（决定 §三 那行的连字符形态）：

    200  https://gitcode.com/JianFeeeee/homeagent-sdk
    200  https://gitcode.com/JianFeeeee/HomeAgent
    404  https://gitcode.com/JianFeeeee/HologramAgent-sdk
    404  https://gitcode.com/JianFeeeee/HologramAgent

## 五、验收

1. 全仓 `HologramAgent-sdk` 计数 = 0（.md/.html/.py/.sh/.yml/.yaml/.txt/.json/.go/.mod/.sum）
2. 全仓 `hologramagent.jianfgit.xyz` 计数 = 0
3. site/index.html 23 条 SDK 链接全指向 homeagentsdk，0 条指向 HologramAgent-sdk
4. curl -L 三条必测均 200（见 §四）
5. `TMPDIR=/home/newqqagent/tmpbuild6 go build ./...` 退出码 0
   （/tmp 已 98% 满，用独立 TMPDIR 避开 No space left on device）
6. git status 干净；11 个改动文件全为 .md/.html/.sh，零 .go 改动
 2026-10-21 19:36:53 +08:00
JianFeeeee
37b8c26675 refactor(docs): 批6a 清理介绍站与文档的旧仓名/旧链接 
改名 HomeAgent → HologramAgent 后，介绍站与仓内文档仍指向旧仓地址、旧站点
域名，点击即 404 / 落回旧站。本批只动文档与静态站，代码零改动。

映射（严格按主管给定的唯一权威口径）：
- github.com/JianFeeeee/HomeAgent → .../HologramAgent（含 /blob /releases /tree）
- github.com/JianFeeeee/homeagentsdk → .../HologramAgent-sdk
- introduce.homeagent.jianfgit.xyz → introduce.hologramagent.jianfgit.xyz
- sdk.homeagent.jianfgit.xyz → sdk.hologramagent.jianfgit.xyz
- 品牌名/链接文本 homeagent-sdk → HologramAgent-sdk（含 `cd homeagent-sdk`
  克隆后的本地目录名，跟随新仓名）

改动面（12 个文件，138 行，纯替换无逻辑变更）：
- site/index.html 36 处：13 处主仓链接 + 23 处 SDK 仓链接（22 个 example/
  与 LICENSE、仓库首页）
- README.md / README_EN.md 各 12 处（9 处 URL + 3 处链接文本）
- assets/docs/{zh,en}/PLUGIN_DEV.md 各 34 处、OVERVIEW.md 各 2 处
- docs/zh/ci-cd-runbook.md 9 处、docs/zh/deploy-runbook.md 2 处（站点域名）
- deploy/scripts/deploy-sdk-site.sh 5 处（注释里的 server_name + 3 处 curl
  探活地址，否则改完站脚本仍在验旧域名）
- docs/git-branching.md 2 处、assets/skills/commondev-discipline/SKILL.md 1 处
  （gitcode module 路径）

刻意不动（动了会坏）：
- 真实目录 third_party/homeagent-sdk（只改 URL 里的 homeagentsdk）
- go.mod 的 module / replace、所有 .go import（module 仍是
  github.com/JianFeeeee/HologramAgent，SDK 仍 homeagentsdk）
- deploy/packaging/package-linux.sh 里的 `replace github.com/JianFeeeee/
  homeagentsdk` 与 clone URL —— 它必须与未改动的 go.mod 逐字一致，属代码非文档
- 数据目录 ~/.homeagent、二进制 homed、产物名 hologramagent_*、
  插件名 homeagent-mail-bridge
- systemd 相关行（homeagent.service / systemctl / journalctl）—— 待上级确认，
  本批不动，清单见汇报
- docs/api/*.md（首行「请勿手改」，生成型）

判据（含变异验证）：
- 三条旧串 grep 全仓清零；third_party/homeagent-sdk 目录仍在
- site/index.html 标签配平（HEAD/WORK 双跑）+ section 数 13→13 未减
- 变异：分别还原 deploy-sdk-site.sh:206、site/index.html:3041、README.md:243、
  ci-cd-runbook.md:11 各一处，以及删一个 </footer>，判据均按预期报红
- go build ./... 通过（仅把 TMPDIR 指到 /var/tmp 规避 /tmp tmpfs 满，仓内文件无关）

未执行任何线上动作：不 push、不开 PR、不重命名 GitHub 仓。注意 SDK 仓在
GitHub 侧目前仍叫 homeagentsdk，本批把文档指向 HologramAgent-sdk 是「改名
在路上」，该仓改名完成前这批 SDK 链接会 404。
 2026-10-21 19:22:02 +08:00
JianFeeeee
9bc2687972 refactor(docs): 补正 git-branching 主仓名，接上批 5-a 改名 
批 5-a 复核发现 docs/git-branching.md 两处仍以 TrueAgent 指代主仓，漏改。
只动这两行，`third_party/homeagent-sdk` 是 SDK 仓目录名，原样保留。

- 第 4 行：`本仓（TrueAgent/HomeAgent）` → `本仓（HologramAgent）`
  （整段收敛成一个名字，不再留 "旧目录名/旧展示名" 的复合写法）
- 第 183 行：`### 主仓（TrueAgent）` → `### 主仓（HologramAgent）`

TrueAgent 在本仓其余 6 个文件里都是磁盘上真实存在的路径 /home/program/TrueAgent
或本机工作副本名，一行未动：deploy/systemd/embed-sidecar.service、
assets/skills/commondev-discipline/SKILL.md、docs/zh/commondev-design.md、
docs/zh/commondev-agent-runtime-design.md、internal/security/store_test.go、site/README.md。

判据口径同步收紧（判据 2）：
- 豁免只允许三类并逐条打印 —— A 仓库 URL（批 4-b）、B 本机真实路径、C 既有契约
  （HOMEAGENT_*、homeagent-sdk/homeagentsdk、homeagent.service、插件名）；
  ~/.homeagent 单列为 D 遗留项（须与 cmd/ 侧同改）
- 原 `TrueAgent/HomeAgent` 常驻豁免已撤销（该串已不存在，留着会掩盖它复活）
- 新增 TrueAgent 守卫：git-branching 内 TrueAgent 必须 0；全仓 TrueAgent 逐行集合
  必须 == base e3584bb 集合减去这两行，命中文件数 7→6
- 新增安装路径断言：/usr/lib、/usr/share/doc、/etc、/var/lib 旧值必须 0

自证：docs/git-branching.md 里 HologramAgent 3 处、TrueAgent 0 处；全仓 TrueAgent
文件数 7→6，逐行与基线 diff 仅这两行。四条判据正向全绿，13 条变异全部被咬住。
 2026-10-21 17:07:46 +08:00
JianFeeeee
931c803421 refactor(docs): 核心仓文档与介绍站展示名改名为 HologramAgent 
只改仓库内文件的纯展示品牌名与已随批 2 落地的安装路径；运行时契约、仓库 URL、
域名、环境变量、可执行名、插件名一律不动。

一、纯展示名（HomeAgent → HologramAgent，共 44 处 / 18 个文件）
- README.md 4、README_EN.md 4（标题、client 变体说明、Windows 安装包名、AGPL 段）
- docs/ 8 个文件 14 处（git-branching 1、ci-cd-runbook 1、commondev-design 3、
  commondev-agent-runtime-design 4、deploy-runbook 1、legacy-issues 1、
  prod-migration-checklist 1、triple-extract-attention 2）
- assets/docs/ 6 个文件 14 处（zh/en 的 OVERVIEW 2+2、ARCHITECTURE 2+2、
  PLUGIN_DEV 3+3）
- assets/branding/mascot-xiaozhai-guide.md 2 处（身份行、标志名）
- site/index.html 6 处（title、meta description、og:title、logo alt、页头字、
  插件卡片文案 "HologramAgent 接入 AgentMail"）

二、安装路径对齐批 2 产物（共 10 处）
- /usr/lib/homeagent → /usr/lib/hologram（7 处：README 2、README_EN 2、
  multimodal-space 3）
- /usr/share/doc/homeagent → /usr/share/doc/hologramagent（3 处：README 1、
  README_EN 1、multimodal-space 1；注意 Doc 路径带 agent 后缀）
- site/index.html 的 19 处 HomeAgent 里，13 处是 github.com/JianFeeeee/HomeAgent
  仓库 URL，属红线整串保留；只改 URL 之外的展示文案（其余 13 处零改动）

三、明确不改（红线 / 一致性冲突）
- site/index.html 的 23 个 github.com/JianFeeeee/homeagentsdk 外链（21 条
  example + 2 条纯仓库），SDK 仓改名属批 4-b，一个未动
- 核心仓仓库 URL、sdk./introduce.homeagent.jianfgit.xyz 域名、HOMEAGENT_ 前缀、
  homed/waiter/hmapdev、.hmap、homeagent-mail-bridge 等插件名、third_party/、
  internal/ 与 cmd/ 全部零改动
- ~/.homeagent 路径本批保持原样：cmd/waiter/main.go:109、daemon.go:290 硬编码
  仍为 .homeagent，全仓无 .hologram 命中；照规格改文档会指向程序不用的目录，
  需与代码侧那条线一起改（遗留项，已单独上报）

判据：文档区展示名残留归零（44 文件）、红线计数与 base e3584bb 逐项相同、
三条变异均被咬住且还原后复绿。
 2026-10-21 17:00:48 +08:00
JianFeeeee
ceb8a7b165 refactor(proc)!: 版本身份只由版本号本身承载，删除全部自定版本号 
内核侧配合 SDK 仓 b2872f3：兼容性不再依赖任何自造版本号。

删除三处自造号：
  - ProtocolVersion（协议号）→ 改为比对主版本段（MajorVersion）
  - shmVersion（共享段 header）→ 改为校验描述符个数（field_count）
  - unifiedVersion（SuperBlock）→ 结构自描述，不再校验

握手契约随之调整：
  HandshakeParams:  protocol(int) → core_version(string)
  HandshakeResult:  protocol(int) → sdk_version 承担判据
  内核比对 MajorVersion(meta.Version) == MajorVersion(res.SDKVersion)，
  跨主版本即拒并提示重编（主版本跃迁 = 破坏性变更的定义）。

为什么废除：额外的号需要人去记得升，而它没有任何结构性约束兜底，
必然腐烂。实证：ProtocolVersion 常量在多次布局变更里只升过一次，
对应的守卫测试长期失败无人察觉（期望 18/1，实际 19/2）。

新增判据：
  - TestProcess_MajorVersionMismatchRejected：跨主版本被拒（testdata/badproto）
  - TestProcess_SameMajorDifferentMinorAccepted：同主版本放行（新增 testdata/oldminor）
    后者是 §七「1.x 内纯追加、不调新面不用重编」规约的落地 —— 若误用全等
    比较，未重编的存量插件会被无谓地全部拒绝。
  两条均经变异验证：改成全等比较 → 前者过/后者挂；删掉校验 → 前者挂。
 2026-10-13 09:39:34 +08:00
JianFeeeee
f3ec45af59 docs: 删除迁移期临时文档，现行内容搬进正式文档 
用户指出迁移评估那批是**过程性临时文档**，迁移已完成就该退场。

## 删除（38 个文件）
- docs/zh/架构迁移评估.md（1621 行）—— 评估稿。开头的「❗现网正在发生的问题」
  （output_send 永远成功 / cgo 超时泄漏 26 次 / stage 污染）**全部已修复**，
  留着是误导性告警。其 §三「目标架构」已被 ARCHITECTURE.md 完整覆盖
  （且后者更细，含子进程生命周期管理）。
- docs/zh/plugin-interface-matrix.md（428 行）—— 迁移基线矩阵。
- docs/zh/experiments/（36 文件）—— 18 项可行性实验，验证的是"该不该迁移"，
  迁移早已完成；实测无任何构建/测试依赖它。

## 现行内容先搬走（不能随临时文档一起丢）
- plugin-interface-matrix §九「接口扩展规则」→ 搬进 docs/git-branching.md 新增 §八
  （只增不减/签名不改、新增必须"插件调用内核实现"方向、hmapdev 模板必须同步接线
  否则全体插件编译失败、"接口纯追加"≠"无需重编"、合回 main 的同步清单）。
- git-branching §六 原写「接口冻结是合回门禁」—— 冻结是**迁移期**约束，v1.1.x 起
  已到期，改为标注失效并指向 §八。

## 引用清理
8 处引用全部改指现行文档：plan.md ×3、两篇设计文档各 ×1、
4 处源码注释（proc/shm.go、proc/process.go、dynamic_proc.go、entry_dispatch_test.go、
proc/bench_test.go）。仅 third_party（SDK 独立仓）保留 1 处，不动。

## 验证
- `go build ./...` 通过；`go test ./internal/plugin/...` 两个包全绿
- 本项目文档**断链 0**（另 2 处断链在 oh_modules 第三方依赖内）
 2026-09-19 19:22:48 +08:00
JianFeeeee
c31b4769bf docs(release): §四 补客户端版本必须与内核同步 + make 门禁 2026-09-15 11:04:31 +08:00
JianFeeeee
39efd27d5e 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
JianFeeeee
1e1fb5320a 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
JianFeeeee
09bd0f5eea 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
JianFeeeee
d989ec7d4d docs: 补「分批上传时后一轮必须全量重算 SHA256SUMS」 
实测踩到：v1.3.10 先传 amd64 的 9 个资产（含只覆盖 amd64 的 SHA256SUMS），
后补 arm64 时按 arm64 那 4 个文件重算 ⇒ 同名附件覆盖 ⇒ amd64 的校验和消失。
校验和是附件的唯一完整性依据，丢了等于没有校验。已同步到技能的同名小节。
 2026-09-13 17:35:02 +08:00
JianFeeeee
5594280c11 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
JianFeeeee
476b24ffed 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
JianFeeeee
7605ff243e docs(git): 修正上一提交的错字（但声两仓 → 但两仓） 2026-09-12 09:01:59 +08:00
JianFeeeee
9e6f7fedf7 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
JianFeeeee
8bebaeb3a5 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
JianFeeeee
39f2eb3677 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
JianFeeeee
06b1efe06a 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
JianFeeeee
8667efae1a 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
JianFeeeee
bbf20229ca docs: 固化当前分支对齐记录（update→feature/plugin-proc-migration） 2026-08-31 12:37:43 +08:00
JianFeeeee
ae363627a8 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