jianf/HomeAgent
1
0
Fork 0
mirror of https://gitcode.com/JianFeeeee/HomeAgent.git synced 2026-09-24 10:58:13 +00:00
Code Issues Packages Projects Releases Wiki Activity
592 Commits 6 Branches 27 Tags
main
Commit Graph

16 Commits

Author SHA1 Message Date
JianFeeeee
4f3de61d8f license: 明确内核 AGPL / SDK MIT 的边界（插件不受 AGPL 传染） 
SDK 仓改为 MIT（同批提交 e97cafc）后，核心仓几处「插件静态链接 SDK 故须同许可」
的论述不再成立，一并更正。

## 边界（现在写清楚了）

- **AGPL-3.0-only 覆盖内核与随包内置插件**：homed、internal/、internal/plugins/
  下 18 个内置插件。§13 网络条款照旧适用。
- **MIT 覆盖公开 SDK**：sdk/ 零外部依赖、只依赖 Go 标准库，不引用内核任何代码。
- 因此**外部插件不是本项目的衍生作品**，作者可自行选择许可（含闭源、商业、
  私有），既不必同许可、也不受 §13 约束。

## 改动

- README.md / README_EN.md「许可」章节：改写静态链接那段，写明上述边界与理由
  （决定许可的是被链接的 SDK 代码，而它是 MIT；子进程隔离不再是关键论点）
- README.md / README_EN.md changelog：**按本仓惯例保留历史原文**，在既有更正
  注记区追加一条「许可口径已变更（2026-09-24）」，而不是去改写 v1.2.0 的原文
  —— 避免伪造当时的语境
- site/index.html footer：状态栏拆成「内核许可：AGPL-3.0-only」+「插件 SDK：MIT」
  两行；声明区分「AGPL（内核与其内置插件）」与「SDK 以 MIT 发布，插件不受传染」
- .gitignore：example/ 注释里的计数 20 → 21（实际 10 个示例 ×2 + qq/plugin_test.go；
  规则本身与「有意保留」的说明不变）

验证：go build ./internal/meta/ ./internal/agent/core/ 通过；官网 1440px 无横向溢出、
无控制台错误，footer 许可两行正确渲染（/tmp/lic-footer.png）。
 2026-09-24 10:55:23 +08:00
JianFeeeee
7587bd82d8 site: 正名「驻留子 agent」+ 删净页面小字注解 
用户两点意见：
1. 那个东西不叫「分诊助手」，叫**驻留子 agent**
2. 页面上加的小字注解全是废话，全删

## ① 正名：分诊助手 → 驻留子 agent

「分诊」只是 offload.go 里对**职责**的描述（triage），
`resident.go` 顶注给的正式名是「驻留子」，`docs/zh/resident-subagent-design.md`
也把它列为独立概念（根 agent / 驻留子 / 工作式轻量子三类）。

7 处全部改正，含图内 SVG 文字、`aria-label`、架构流程图、FAQ 正文：

| 位置 | 原 | 现 |
|---|---|---|
| 图 5 框标题 | 分诊助手 | 驻留子 agent |
| 图 5 框内第二行 | 临时驻留子 | （删，与标题重复） |
| 图 5 的 aria-label | 转投给分诊助手 | 转投给驻留子 agent |
| 正文 | 转给一个临时驻留的**分诊助手** | 转给一个**驻留子 agent** |
| 架构图转投分支 | → 转投临时分诊助手 | → 转投驻留子 agent |
| FAQ | 这正是「分诊助手」的用途 | 这正是驻留子 agent 的用途 |
| CSS 注释 | 分诊助手接到消息 | 驻留子 agent 接到消息 |

## ② 删掉 11 处注解小字

原则：**复述图上已画出来的、或标题已说过的** → 删；
**承载数据**（插件版本 / 源码路径 / SVG 图内必要标签）→ 留。

- `.duty-note` ×6：架构图里 6 个阶段下面那行灰字
  （「构建消息与工具表 · 插件可在此短路」等）—— 阶段名本身已经说清，
  而这 6 行会把循环框右半边撑空
- `.flow-note`：重复解释 `on_input` / `before_output` 跑在什么时候
- `.dv-caps` ×3：图 4 的「任何中断都能插它前面」「被打断的现场压入中断栈」、
  图 5 的「不必干等」—— 图上插队动线和回执 chip 已经把它们画出来了
- `.dv-note` ×2：图 2「实测：statically linked，无动态依赖」、
  图 3「实测整段写入+读回 3.5µs」—— 数字重复
- `.dv5-tnote`：「默认关闭，需部署方打开」—— FAQ 里有完整说明（含理由）
- `.duty-ev` ×4 + `.sm` ×4：证据行/注释行，数字并回正文
  （「实测整段写入 + 读回 3.5µs。」等）

## ③ 删小字的连带修正

- **11 处死 CSS 全部清掉**（`.duty-ev` / `.flow-note` / `.dv-caps` /
  `.dv-note` / `.dv5-tnote` / `.sm`），单文件不留无人引用的规则
- 循环框删掉 6 行灰字后**右半边空了一大块** → 改为 `fit-content` 收窄居中

## 自己踩到并改掉的坑

- 循环框收得太窄（16rem），回边徽标「有工具调用则回到 ①」**压住**
  `after_toolcall` → 加 `min-width` 并加大底部 padding
- 想让循环框占满宽度，试过**阶段项排两列** → 截图发现编号被 grid
  按行填充排成 `1/3/5 · 2/4/6`，线性流程顺序全乱。已回退单列，
  并把这条教训写进 CSS 注释（免得后人再试一次）
- 图 5 触发条件框删掉小字后留白偏大 → 高度 56→42

## 验证

- 三档宽度（1440/768/390）：无横向溢出、回边徽标与阶段项**零重叠**、
  文字未被截断
- 深浅双主题 / JS 禁用 / reduce 回归全绿；控制台零错误
- 死 CSS 计数全部归零；「分诊」全站残留 0
- CSS 括号平衡，文件 141,847 字节（原 143,960，净减 2.1KB）
 2026-09-21 10:23:06 +08:00
JianFeeeee
7b7d405463 site: 重做第 3/5 张示意图 + 删冗长文案 + 修中文排版 
用户反馈：3/5 页面图片不够精致、动画单调；hero 与架构节两句文案啰嗦；
图 1 那句注释要删。

## ① 删掉两处冗余文案

- 图 1 的 `<p class="dv-note">箭头只进出插件 —— 内核一列都没有</p>`：
  图上已经画出来了（光球只打插件、内核周围无连线），注解是重复
- 架构节副标题的「插件可改写或短路」：与组件表里 `Stage` 那行完全重复
  （那行还更具体，带 1/4/2 的阶段分布）

## ② hero 副标题重写

原文「内核只管编排、记忆与调度，消息 / 文件 / 网络 / 设备一律交给插件。
插件崩了不牵连内核 —— 换掉一个二进制就热重载。」三重堆叠、句子太长。

改短后又发现**两处与源码不符**，一并改准：
- 「热重载」不是崩溃后的行为。崩溃走的是退避重启
  （`scheduleProcRestart`：1s/2s/3s，`AutoRestartEnabled` 默认 true），
  `ReloadOne` 是换二进制那条路径。混成一句等于说错。
- 改为「崩了自己重启，波及不到内核」。

## ③ 图 3（共享内存）：从稀疏线框重画

原图 19 个元素、层次扁平。重画后 53 个元素、三层递进：

- 两个进程做成带玻璃高光的卡片，各标自己的**虚拟地址**（0x7f2a… / 0x55c1…）
- 中间一句桥接：「不同虚拟地址 · 同一物理页」——这才是零拷贝的关键
- 物理页外框呼吸描边 + 极淡填充
- 段内标出 `header`（魔数·版本）与 `arena`，并加**字节刻度**，
  把「一片区域」讲成「有结构的区域」

## ④ 图 5（长任务转投）：填掉大片空白

原图下三分之一完全空着，且「两种出路」只写在文案里、图上没有任何体现。

- 主 agent 加**忙碌进度条**（一直爬不到头，呼应「占住很久」）
- 积压消息由 2 条改 3 条、宽度递减成「一摞」，并逐条被取走
- 右上空白填入**触发条件**，给的是源码实测默认值
  （`defaultOffloadBusyAfter = 5min`、`defaultOffloadMinPending = 3`），
  并注明「默认关闭，需部署方打开」
- 新增回执区：`① 简单 → 直接办完，发回原通道` /
  `② 需主 agent → 回「忙碌中，请稍候」`，并用光点示意回执送达用户

## ⑤ 排版：中文之间夹空格

改文案时实测发现正文里有「实时 渲染」这类中文间空格 —— 源码换行被浏览器
渲染成一个空格。找出真实渲染有空格的位置并修掉（改用 innerText 判定，
textContent 会把 `<em>` 等块边界误判为空格，实测误报了 2 处）。

## 自己踩到并修掉的几个坑

- 「各自的虚拟地址」两句标签被竖向虚线穿过（压字）→ 改为一句居中桥接
- 图 3 标题靠左时被 `x=72` 的写入虚线穿过 → 改居中
- 玻璃高光整块铺满像蒙了层白纱 → 收到上半部、透明度 .3
- 巡行光点框看起来像页内多了一层框 → 去掉，改为外框呼吸
- 内层标题与外层桥接都在说「同一物理页」→ 内层改为描述段布局

## 验证

- 深浅双主题逐图截图核对（图 3、图 5 各两套）
- 动画：图 3 从 5 → 11 个动画元素、图 5 从 8 → 10；元素总数 19→53、17→45
- reduce 下新增的 CSS 动画（physBreathe、dv5-pile、忙碌条）全部停；
  SMIL 仍靠 pauseAnimations，8/8 SVG 已暂停
- 回归：深浅主题 / JS 禁用 / reduce / 390·768·1440 三档，零横向溢出、无控制台错误
- 结构：CSS 括号平衡、HTML 无未闭合标签
 2026-09-20 23:37:16 +08:00
JianFeeeee
5d395116d1 site: 修正 FAQ 三处与源码不符的描述 
用户指出「常见问题部分描述不太符合事实」。逐条对着源码核了六条，
查出三处不准（第 4 条是实质性误导），另修掉一个由此暴露的滚动缺陷。

## ① 第 3 条：「L4 是内核保留的」漏了一半

源码 `interruptLevel(evt, privileged)` 有**两条**放行 L4 的路径：
`privileged=true`（内核）与 `isKernelLevelSource`（编译期内置插件）。
`scheduler.go:74` 的注释也写明「只给内核与编译期内置插件」。

原文只说「内核保留」，会把内置插件的能力说没。已补上。
（「外部插件声明 L4 会被夹到 L3」这句本身没错，`clampPluginLevel` 确实如此。）

## ② 第 4 条：自动转投默认是关闭的 —— 原文读起来像默认行为

`DefaultOffloadOptions()` 返回 `Enabled: false`，源码注明理由：
「默认关闭、由部署方显式打开，与『显式才是特权』同一条理由」。

原文说「内核拉起临时驻留子接手」，通篇没提这个前提，读者会以为开箱即用。
已补上「默认关闭」并给出默认阈值（实测 `defaultOffloadBusyAfter = 5min`、
`defaultOffloadMinPending = 3`，原文只说「忙超阈值」「积压够多」，没给数）。

## ③ 第 5 条：「媒体跟着记忆块走」不完整

`payloadHeld()` 的存在说明有**共享**一说：同一份字节可能被多个块持有，
此时**不删**。两个删除点（`medialoop.forgetPayloads` 与 `sdk/memory_impl.go`）
都各自做了 `stillHeld` / `payloadHeld` 检查，注释写明
「同一张图可能被多个块引用」。「跟着块走」会让人以为按块计数即可。
已改为「如果同一份字节仍被别的块共享，则不删」。

## 核对无误的四条（未改）

- 第 1 条：`现场保存/恢复`、`中断栈` 都是 `scheduler.go` 的原词；四级中断、
  上下文预算、蒸馏与召回均在
- 第 2 条：三通道准确（`proc/shm.go` 顶注：`stdio JSON-RPC` 控制面 /
  `shm + 偏移` 数据面 / `eventfd` 通知面「事件环 post-and-forget」）；
  「摘除工具、阶段与通道」对应 `UnregisterPluginTools` /
  `UnregisterPluginStages` / `releasePluginChannels`；`onProcCrash` 注释即
  「摘注册面、喂健康计数、排一次重启」
- 第 6 条：`go:embed adapters/*.lua` 真嵌入；9 个名字与 `internal/lua/adapters/`
  下文件逐一对应（`server.lua` 是网关脚本，不计入）

## ④ 顺带修掉：FAQ 全部展开后滚不到底

改动后我照例量了末尾能否到底，发现**全部展开时卡住、页脚不可见**：
展开后 faq 712 + footer 367 = 1079 > 一屏 900，`mandatory` 又把滚动锁住。

这里走了两次弯路，都记进注释了：
- 先想只让 faq 退出吸附 → **死锁**：它下方没有吸附点，而 mandatory 只允许
  停在吸附点，实测卡在 plugins 的吸附位（y=9455）不再前进
- 阈值先误用「视口高」→ 展开后 faq 高 712 < 892，判不出超限，类根本加不上

最终改为「展开超过『视口高 − 页脚高』时整页切到自由滚动」，
因为 faq 是最后一个吸附节，它一旦装不下，末尾就必须整体自由。

## 验证

- 折叠态：到底=true，页脚可见，faq 标题不被导航遮挡（h2 顶 210 > 67）
- 展开 1 条 / 展开全部 6 条：两种状态都到底=true、页脚可见
- 一滑一页仍生效（8/8 次停靠不同节，72px 偏移为导航高度）
- 深浅双主题 / JS 禁用 / reduce / 390·768·1440 三档：全绿，零横向溢出，无控制台错误
 2026-09-20 22:49:56 +08:00
JianFeeeee
fc8f153e34 site: 修首屏滚不到底 + 交错行出入方向 + 让示意图真动起来 
用户反馈三点：① 拉不到最下面 ② 文字与图片没有进出动画，单调
③ 图片仍是「框框住文本」，且希望有「外界光球打到插件上」。

## ① 滚不到底：真 bug，且是两个独立根因叠加

实测（滑到底后读 scrollY）：停在 10283，上限 10669，**差 386px**，
页脚完全不可见。两个原因：

- **末尾两节合计超过一屏**。faq 高 635 + footer 367 = 1002px > 一屏 828px。
  `scroll-snap-type: y mandatory` 只允许停在吸附点，于是浏览器被迫二选一：
  要么 faq 标题对齐（则页脚滚不到），要么页脚可见（则标题被导航压住）。
  实测两种坏法都出现过：h2 顶 = -57 / -38（导航底 67）。
  修法：FAQ 六条改双列（省下约 190px），收尾段取消整屏高度，
  合计压到 762px，两个要求即可同时满足。
- **只在 footer 单独设吸附点会形成死锁**。试过给 architecture 设
  `scroll-snap-align: none`（它高 1180px），结果前一个吸附点把它自己吸回来、
  后面又无吸附点接住，实测卡死在 y=5791，怎么滑都不动。
  教训写进注释：高节退出吸附不是解法，「装得进一屏」才是。

## ② 交错行：方向与布局相反（结构性错误）

原文给每行写死 `slide-l`（文）与 `slide-r`（图）。但翻转行里图在**左边**，
却仍从右侧飞入 —— 图穿过文字进场，方向与布局相反。5 行里 3 行错。

修法不是逐行改正，而是**从布局推导方向**：`.alt:not(.flip)` 文左图右、
`.alt.flip` 图左文右，方向跟着 `.flip` 走。这样不可能再写错。
退出时不加 `.in`，transform 回到同侧 ——「从左进就从左出」是自动的。

## ③ 示意图：从静态线框变成有语义的动画

现状实测很糟：5 张图共 116 个元素，**只有 4 个在动**（各 1 条虚线），
图 2 完全静止 —— 用户说「框框住文本」是准确的。

按每张图的语义给它自己的动作（13 种 keyframes，47 个动画元素）：

- **图 1 隔离**：外部光球从画面外飞入，四种颜色命中四个插件，
  激起涟漪 + 插件闪一下；内核一列都没有。这正是「外面的一切都落在插件上」。
- **图 2 零依赖**：四项依赖被**逐条划掉**。用 `pathLength=1` + `stroke-dashoffset`
  让线自己「划」过去，不是淡入。
- **图 3 共享内存**：写入/读回两个包沿链路跑，arena 上有光带自左向右扫过。
- **图 4 优先级**：金色包沿四条曲线**插队**到 L1–L4 之前；
  四级强度条依次点亮；队列条逐条被取走（先到先处理）。
- **图 5 长任务转投**：积压消息被接走飞向分诊助手，收到时闪一下。

配套修掉三处我自己引入的缺陷：
- `.dv-pkdot` 原用 `pkPulse` 动 `r`，与行进包叠加会闪烁 → 改只动透明度
- `.dv-ripple:nth-of-type(2n)` 按 `<circle>` 计数，误配到数据包圆点，
  四个涟漪全被染成金色 → 改显式逐色
- 涟漪原画在插件框**内部**，像框里画了个圆 → 移到框下层，从背后漾开

## ④ 顺带发现并修掉的真问题

- **CSS 的 `prefers-reduced-motion` 管不到 SMIL**：实测 reduce 下 6 个
  数据包照跑。加 JS 调 `svg.pauseAnimations()`，实测 8/8 SVG 已暂停。
- **窄屏横向溢出 26px**：源于我这次加的入场位移（`translateX(42px)`）
  在未入场时探出视口。修法是 `overflow-x: clip`（不用 hidden，避免新建滚动容器）
  并窄屏收到 ±20px。实测 390/768/1440 三档溢出均为 0。

## 验证

- 滚动：到底=true，页脚可见，faq 标题不被遮挡（h2 顶=210 > 导航底 67）
- 方向：5 行全部「文在左侧就从左进」，翻转行正确反向
- 入场：逐节停留 13 节全部入场，0 未揭示；
  滑到底后 23 个 opacity=0 的元素**全在视口上方**（退场生效），无一是「场内却不可见」
- 回归：深浅双主题、JS 禁用、reduce、390/768/1440 三档 全绿，无控制台错误
- 结构：HTML 解析无未闭合，CSS 括号平衡
 2026-09-20 22:37:06 +08:00
JianFeeeee
3374e7dbd9 docs: 更正三处无实测支撑的性能断言 
用户指出现有文档里的性能数字可疑。逐个实测后发现三类问题，都不加改原文地
标注更正（历史条目保留原文，仓内已有此惯例）。

## ① 「崩溃到恢复 <1s」——从未成立

写于 v1.0.0 发版说明。但**当时的退避代码就已是 1s**（查 v1.0.0 tag 的
`procRestartBackoff = time.Second`），首次重启就要等 1s。

实测（新增临时测试测量 scheduleProcRestart 延迟）：

    第 1 次崩溃 → 1s      第 2 次 → 2.001s      第 3 次 → 3.002s

顺带纠正我自己刚在站点写错的阈值：并非「崩 3 次停下」。实测第 **4** 次
才停（`procMaxRestarts=3`，判定为 `n > 3`），前 3 次都会重启。

## ② 「RPC 往返 p50 24.1µs」——量级对、数字不符

实测 `BenchmarkToolInvoke`：inline/small **30.4µs**、frame/small 51.5µs、
inline/large 767µs、frame/large 398µs。原文与实测同为几十微秒量级，
但具体值对不上，且未注明测的是哪种 payload。

## ③ 「CLIP 实测常驻 1.15GB」——采样点不对（6 处）

实测加载 chineseclip 两塔，RSS 会**自己降下来**：

    加载前      0.00 GB
    两塔加载后  1.59 GB   ← 峰值
    GC + 静置     0.89 GB   ← 稳态（内核回收未用页）

1.15GB 落在两者之间，既不代表峰值也不代表稳态。线上稳态实测 0.39~0.58GB
（更长时间静置后更低）。同源问题：qwen3vl 的「常驻 9.4GB」实为**峰值**，
其视觉塔本就是按需加载（源码注释：每张图约 1.6GB，故按需）。

6 处全部改为「稳态 X（峰值 Y）」双值，消除口径歧义：README 中英、
docs/zh/multimodal-space.md、config/registry.go（2 处 + 1 处注释）、
providers/chineseclip/tokenizer.go。

## 验证

- `go build`（含 `-tags onnxruntime` 与不带）与 `go vet` 均通过
- 全仓 `grep 1.15GB` 已清零
- 测量用的临时测试文件已删除，无残留
 2026-09-20 19:56:49 +08:00
JianFeeeee
ca6f4c510c feat(site): priority 图补上「排队输入」这一类（用户指出的漏项） 
## 漏项

文案写「输入走两条路」，但图上只有 L1–L4 —— **排队的完全没出现**。
源码 `scheduler.go` 开篇就写明是**两类别**：

- TaskInterrupt（InjectInterrupt*）：带 L1..L4，可抢占
- TaskQueued（InjectText*/InjectInputSync*）：**无级别**，可被任何中断打断

「级别只属于中断」是这套调度模型的关键一句，图里不表达就等于漏了一半。

## 改法

图改成左右两列，标题直接写清差异：

    中断 · 带级别            排队 · 无级别
    ├ L4 内核独占            ├ 队列条（先到先处理）
    ├ L3 需及时处理          └ 任何中断都能插它前面
    ├ L2 消息类                      │
    └ L1 完全可等                     │
        └───────────┬──────────────┘
                正在跑的任务

- 排队列用**虚线框 + 素色条**（不发光），与左侧的实线发光级别条刻意区分 ——
  「无级别」这件事本身就该在视觉上体现
- 两路汇入「正在跑的任务」，并标注「同一时刻只一个」

## 顺带修的两处

- **浅色下排队条看不见**：原先复用 `gCard`，而浅色下 gCard 是白的，
  白底白条等于没画。改用独立的 `--dv-queue-item` 令牌
- **横向虚线穿过队列条**：原想表达「处理方向」，结果画在了条内部。
  改为右侧竖线 + 向下箭头

## 验证

- 双主题：控制台错误 0、横向溢出 0、图元零越界
- 一滑一页仍生效；JS 禁用 24/24 可见；reduce 下吸附停用
- 390/768/1440 溢出均 0
 2026-09-20 10:39:53 +08:00
JianFeeeee
88923ed663 feat(site): 示意图升级为玻璃面板 + 修 priority 图两处错误 
## 根源（用户指「图太平，没有高级 UI 效果」）

问题不在画得不够花，而在**手法本身就平**：纯 SVG rect + 平面文字浮在平坦
背景上，本质上就是工程草图。换基础：

- **玻璃面板**：每张图裹一层带内上高光、内下厚度、外分层投影的玻璃底 +
  `backdrop-filter: blur(8px)`，图形才像「浮在界面上」而非浮在空背景上
- **顶部柔光 + 细颗粒**：径向渐变给受光面，`feTurbulence` 噪点抿掉矢量图的塑料感
- **渐变节点 + 投影**：所有节点从纯色填充改为竖向渐变面 + `feDropShadow`
- **悬停提亮**：`fLift` 滤镜（更远的阴影 + 青色泛光）
- **流动虚线**：连接线 `dashFlow` 动画，看起来「有东西在跑」
- 全部走主题令牌，深浅各自调参（浅色受光方向相反）

## 修 priority 图两处真错误

**① 文案与源码语义错位**（用户报的）
原文写「可以等的 / 不能等的，不能等的再排 L1–L4」——
但源码 `LevelBackground = L1` 的注释是「**完全可等**」。我把 L1 归进了「不能等的」。
实际是：**排队无级别（谁都能插它），中断才带 L1–L4**。已改。

**② L4 文字溢出框外 57px**
`dv-ts` 是 `text-anchor: middle`，但我按左对齐给了 x=46，长的那行
（「L4　内核独占 · 立即打断」）以 46 为中心向两边展开 → 左溢 57px。
新增 `.dv-tsl`（`text-anchor: start`）专供左对齐行。实测四行现均整齐落在框内。

## 顺带修

- 「抢占」标签贴边 99.8%，玻璃面板内边距会裁掉它 → 整条线内移
- 抢占方向原为「从 L4 顶部绕出去悬在半空」，既没连上目标也读反了 →
  改为「从级别条右侧指向正在跑的任务」
- 图 4 内容仅占 viewBox 70%×71%（其余图 88–93%），显空 →
  重画为「强度条背景 + 级别徽标 + 场景标注 + 抢占回边」，现 81%×90%

## 验证

- 双主题：5 面板、控制台错误 0、横向溢出 0
- **全部图元与文字零越界**（含 viewBox 内边界检测）
- 一滑一页仍生效；JS 禁用 24/24 可见；reduce 下 snap 与流动动画均停
- 390/768/1440 溢出均 0
 2026-09-20 10:33:20 +08:00
JianFeeeee
631963fdc7 feat(site): 总起页改为「真正的 AgentOS 长这样」+ 修页脚状态栏不可点 
## 总起页：从对比改为展示（用户要求）

前几版是对照表（「别人说 X → 我们要做到 Y」）。用户指出重点不是对比，
而是**把自己作为「真正的 AgentOS 样例」展示出来**。改为四张并列卡片，
每条给「机制 + 可测数字」，不做比较。

标题「真正的 AgentOS，长这样」；四题：隔离 / 调度 / 通信 / 资源 ——
操作系统躲不开的四道题，逐题给答案。

## 文案改了第三轮（用户指「读着太难受」）

按「短句、有节奏、不堆从句」重写四段正文。举一例：

  旧：插件不是进程内的一个库，是内核 spawn 的独立进程。崩了就把它的
      工具、钩子、通道一并摘掉，其余照跑。
  新：插件不在内核里，是另一个进程。崩了就把它注册的东西一并摘掉，其余照跑。

## 修页脚「状态」栏不可点（用户报的 bug）

三行原为 `<span class="muted">` 死文本，点不动。改为链接：

- 最新发布：v1.3.x 线   → /releases
- main 在研：1.4.0      → blob/main/internal/meta/meta.go（版本号的实际来源）
- 许可：AGPL-3.0-only   → blob/main/LICENSE

## 一处自查纠正

我一度在卡片里写「插件崩溃 → 恢复 <1s」，那是照抄 README 的旧说法。
查源码 `dynamic_proc.go` 发现退避实为 **1s / 2s / 3s**（`procRestartBackoff=1s`，
5 分钟内崩 3 次 `procMaxRestarts=3` 即停手等人），**<1s 不成立**。
改为如实写明退避序列与停手机上阈值。README 那句待另开一轮核实。

## 验证

- 双主题：4 卡片、控制台错误 0、横向溢出 0
- 一滑一页仍生效（6 次滑动偏差恒为 72px = scroll-padding-top）
- JS 禁用 24/24 可见；reduce 下 snap 自动关闭
- 390/768/1440 溢出均 0
- 页脚 9 个 gitcode 目标逐个对照 origin/main 的树：**全部存在**
  （不只看 HTTP 200 —— gitcode 对错误路径也返回 200，此前踩过）
 2026-09-20 10:11:02 +08:00
JianFeeeee
4078f3ac0a feat(site): 重写首屏文案 + 交错图文布局 + 一滑一页 
## 口号与文笔（用户指「不够响亮、部分文笔不好」）

Hero 改为「是…更是…」句式：

  是记得住的管家 / 更是从不让你干等的搭档

## 五个设计决定：从卡片改为交错图文

原来 4 张卡片平铺。改为 5 行交错（文/图左右互换），每行配一张内联 SVG
示意图，纯 CSS + 主题令牌，深浅自适应，零外部依赖。

**换掉一条、新增一条**（用户指出「插件跑在独立进程」不算特色 —— MCP、LSP
都这么做，不是差异点）：

| | 内容 | 依据 |
|---|---|---|
| ② | 部署，从未如此便捷 | 实测插件 `statically linked`、`not a dynamic executable` |
| ③ | 数据如水，随流，随改，随走 | 共享内存 + 相对偏移零拷贝；实测整段写入读回 3.5µs |

标题按用户给的句式写（②③ 原文照用），正文不给形容词、给可核验的做法与数字。

## 一滑一页

`scroll-snap-type: y mandatory` + 每节 `min-height: 100svh`。
为此把 features 的 5 条决定各拆成独立 section（原 2.74 屏塞 5 行，
mandatory 下会锁死底部），architecture 的流程图也单独成节。
现 13 节，实测连续 8 次滑动精确停在第 1..8 节，间距 828px = 一屏。

## 两处实测纠正（都是我先判断错、再被数据推翻）

1. **`proximity` 做不到「一滑一页」**：实测滑 500px 落点就是 500，离最近
   节边界 395px，不触发吸附 —— 只是「有时粘一下」。改用 mandatory。
2. **我误报 architecture「底部锁死」**：按 `h > innerHeight` 判定，忽略了
   溢出行仍可滚动。用真实 wheel 实测 13 节末元素全部可达（含该节 828 < 900）。
   所以没有锁死，压缩 vertical rhythm 是顺带的，不是修复。

## 验证

- 深浅双主题：13 节 / 5 交错行 / 5 示意图、控制台错误 0、横向溢出 0
- 一滑一页：8 次滑动停在 8 个不同节，落点间距精确 828px
- 72px 落点偏移经查是 `scroll-padding-top`（导航高 67px），确保标题不被遮挡 —— 有意为之
- JS 禁用 24/24 可见；reduce 下 snap 自动关闭（`prefers-reduced-motion`）
- 390/768 无 snap（窄屏强制一屏反而难受）；1024/1440 启用
- 真人式滚动（wheel 与 400px 步进两种）未揭示元素均为 0

注：本轮前期用了几个 Python 补丁脚本改 HTML，用户指出「不好」。后续改为
直接编辑以产出可审阅的 diff，脚本已删除。
 2026-09-20 09:46:18 +08:00
JianFeeeee
9b26db45bc fix(site): 逐条对照源码修正描述（含两处真错误） 
上一版有几处表述与源码不符。这轮把页面上每条可核验的说法都对着代码重新查一遍，
改掉 15 处，其中两处是**事实错误**而非措辞问题。

## 事实错误

**① L4 的归属说反了（FAQ）**
原文让读者「用更高级别的中断（如 L4：内核与内核级插件）」插队，暗示插件能用 L4。
源码 `scheduler.go` 的 `clampPluginLevel` 把 **>L3 一律夹到 L3**，注释也写明
「L4 由内核独占（panic、内核事件 selfip）」。照原文写插件会静默拿到 L3。
改为：插件可声明 L1–L3，L4 是内核保留的「立即打断」。

**② 驻留子的父侧动作列错**
组件表写「父可查看/收发/压缩/回收」。"收"不存在 —— 源码的动作集是
`list | create | send | inspect | compress | reclaim | destroy`，
子持有状态面由**父 pull**（resident.go 开篇注释：父持登记表，子持 inputch 处理表，
父 pull 不打断子）。改成「查看/发送/压缩/回收/销毁，子是父拉取而非推送」。

## 措辞不准确（12 处）

- **Context 层**「最近若干条受保护」→ 源码 `pCount := 10` **写死十条**；
  「预训练词向量 → 余弦相似度，TF-IDF 回退」→ 实为优先稠密向量余弦、
  未配置时退到稀疏词向量（TF-IDF / fastText）；「自动下沉」→ 归档进 Document 层
- **PluginSDK「四通道」**→ 不是四个"通道"，是三面接口（工具/钩子/事件）+ 输出通道声明
- **管道「7 个阶段钩子」**→ 会被读成都在管道内。实际分布是进管道前 1（on_input）、
  轮次中 4、收尾 2（before/after_output），两处都标明
- **sanitizer** 只写了"清工具调用残留"，漏了它更常做的是洗坏 UTF-8/U+FFFD/ANSI
  （而这类字节会被模型复读），且不注册工具只挂钩子
- **rss**「推送通知」→ 实际是按间隔轮询 + 中断注入；补上"订阅时记历史条目，
  所以订一个源不会把旧文章全推一遍"
- **memo** 补上可核验的机制：每 5 分钟检查未完成待办
- **ocr / bili** 补外部依赖（tesseract + chi_sim / yt-dlp）—— 不写清楚装完才发现缺
- **mc**「两阶段激活」原样照抄没解释；实为「想连着（意图）」与「确实连着（连接）」
  两个状态分开，所以 bridge 被 kill -9 后能自动重登恢复会话
- **qq** 一句话太单薄，补 20 工具 + 权限模型要点（身份绑帧、取交集、前缀拒绝）
- **a2a / music / weather** 分别补：两个方向与端点、只读无副作用、NoMemory 取舍

## 顺带修掉两个我上一轮引入的 HTML 缺陷

用行替换时失手：Context 卡丢了一个 `</p>`、mc 卡多了一个 `</span>`。
这次写了栈式配对检查才发现（简单的计数对比看不出来）。

## 验证

- 栈式标签配对：p/span/div/button/code/section/h2/h3/details/ul/ol/a/li **全部平衡**
  （修复前 p 差 1、span 差 -1）
- 事实终检 10/10：内置插件 16（all.go 导入数）、LLM 适配器 9 且**逐个名字对上**、
  Go 行 109241→109k、go.mod 1.25.0、L4 归属、resident 动作、Stage 分布、备案号
- 浏览器回归：深浅错误 0、JS 禁用 47/47 可见、reduce 动效停、390/768/1440 溢出 0、
  滚到底未揭示元素 0
- mc 工具数：本写「12 个动作工具」，实测 `tp+"act"` 去重后 activate/deactivate/status
  之外是 **11** 个，已改
 2026-09-20 08:48:15 +08:00
JianFeeeee
47052cb115 fix(site): 更正媒体机制描述 + 页脚补备案号 
## 描述性错误（用户指出）
1. **「引用计数 GC」已不存在**。「有引用绝不删」「媒体靠引用计数 GC」
   两处都在讲一个已废弃的账本 —— 实测源码里已无 media_refs/ref_count，
   `internal/memory/media/media.go` 明确写「这不是 GC，也不看引用计数」。
   现行规则是「删除持有它的记忆块即删内容」，与文本块同一套
   （medialoop.go 的 payloadHeld 只在确认无块共享时才删字节）。
2. **「描述才是持久语义」整张卡已过时**。旧实现靠视觉模型生成的描述当索引；
   现已弃用 —— `mediaref.go` 写明标签「不再包含任何生成的描述文本」，
   图片改按统一空间向量检索，`graphmedia.go` 还带一个把旧描述式实体
   迁移成原生记忆块的迁移函数。卡片改为「图片靠自己的向量被检索」。

## 备案号
页脚补 豫ICP备2024074105号-1 与 豫公网安备41070202001579号，
链接到 beian.miit.gov.cn / beian.mps.gov.cn。取值来源是现网
门户配置（/root/portal/dashy/conf.yml），未凭记忆编造。

## 验证
深浅双主题下渲染正确、两条链接 href 实测无误、无 JS 错误。
 2026-09-20 00:00:23 +08:00
JianFeeeee
09298886a2 feat(site): 「一条消息进来之后」改为真正的流程图 
原来是 ASCII <pre> 图。它有三个问题：

1. **画不出循环**。真实执行序是 7 步状态机，其中工具循环要回到开头
   再来一轮 —— ASCII 只能表达上下关系，这一点只能靠文字暗示。
2. **7 个钩子排成一行是错的**。on_input 在进管道前跑，
   before/after_output 在**全部轮次结束后**才跑一次；把它们与管道内的
   钩子并列，读起来像一条直线。
3. 漏掉了 post_action 之后才发生的工具调用，以及"上下文裁剪 + 相关记忆召回"
   这一步（在 after_toolcall 里）。

## 现在的结构
五层节点 + 分支 + 循环体：
外部输入 → 输入调度器（三条分支：入队列 / 抢占 / 转投）
→ 处理管道 →〔① pre_action ② LLM ③ post_action ④ before_toolcall
⑤ 执行工具 ⑥ after_toolcall〕↻ 循环 → 三层记忆 → 输出通道

事实全部对照源码核过（不是照抄旧图）：
- 7 个 Stage 常量取自 SDK `third_party/homeagent-sdk/sdk/plugin.go`
- 顺序取自内核 `internal/agent/core/task.go` 的 Step 状态机
  （StepPrepare→StepLLM→StepToolBegin→StepToolExec→StepToolAfter→StepTurnEnd）
- 脚本末尾补一句说明 on_input / before_output / after_output 的时机

## 视觉
节点用色与三层记忆的三色一致（蓝=Context/青=管道/金=Graph，紫=转投）；
连接线上的光点错峰下行，序号依次点亮。全部是内联 SVG-free 的纯 CSS，
无外部依赖。

## 关键取舍
- **删掉了贯穿全图的中轴线**：节点背景是半透明令牌，轴线会直接透出来，
  实测在「处理管道」里穿过整个编号列表，看着像画错了。连接线本身就是主轴。
- **循环回边改为内嵌徽标**：先做成从框底绕出的弧线，但它会压到下一条
  连接线 —— 同样像画错。
- **给连接线补了静态箭头**：动画关掉时（reduce）方向也要看得出来。

## 验证（独立 headless 实跑）
深浅双主题控制台错误 0、页面溢出 0；图内溢出 0（390/620/900）；
**JS 禁用下 14 个节点全部可见、7 个钩子名齐全**（流程图是内容不是装饰）；
reduce 下光点/图标动画确为 none 而静态箭头仍在（宽 7px/2px）；
**7 个钩子名与 SDK 常量逐一比对通过**，防止文案漂移；
滚动到底未揭示元素 0。
 2026-09-19 22:38:06 +08:00
JianFeeeee
db8534e315 feat(site): 文案精简 + 插件可点击 + 版面精致化 
## 文案（净减约 25%，信息量不变）
删的是解释性赘语与重复限定，不是信息：
- 「内核不直接读写任何外部世界…于是「内核有多可信」与…」→「内核不碰任何外部世界…可以分开评估」
- 「大多数框架先写功能再补边界。HomeAgent 反过来：先把边界和调度定死，再往上加能力。」
  →「先定边界与调度，再加能力。」
- FAQ 六条逐条收紧；副标题从句子改回短语
- AI 声明与许可段去重复（两段都在讲同一件事）

## 插件徽章从装饰变为可交互（这是用户报的「无法点击」）
每个徽章现在是真按钮：点开显示该插件的**版本 + 用途**（取自各 plugin.json，
共 20 个），可多开、可收起，末尾「展开全部 20 个」一次全开。
键盘可达（Enter/Space），选中态用 aria-pressed 表达。
初版是纯 <span>，带 hover 效果却不可点 —— 看起来能点但点了没反应。

## 修正一处事实错误
统计卡原写「**36 外部插件**」。实测 36 是**加载总数**（16 内置 + 20 外部）；
外部插件实为 20 个。同时：
- 「110k Go 代码行」→ 109k（实测 109,241）
- 「10 LLM 协议适配器」→ 9（server.lua 是 zen 网关脚本，不是厂商适配器）
每张卡补一行小字说明口径，避免再被误读。

## 版面
section 统一 4.5rem 节奏、卡片内边距与标题间距收敛、组件表代码列定宽对齐、
统计卡加口径小字、三层记忆卡收紧。插件选中态从实心青底（20 个齐亮像一堵墙）
改为淡青底 + 主色描边，并给 color-mix 加了 rgba 回退。

## 验证（独立 headless 实跑，全部通过）
深浅双主题 console 错误 0；JS 禁用 47/47 可见且插件卡默认全隐（0 张）；
reduce 下粒子停、全可见；主题切换刷新保持、首绘无闪白；
390/768/1440 横向溢出均 0；移动端点插件正常展开；
插件交互逐项验过：单击展开 → 再点收起 → 多开 3 张 → 全展开 20 张 → 收起。
★ 一度报「19 个元素未揭示」，查证是我测试脚本没滚动所致 ——
逐步滚到底后实测 0 个未揭示，非真回归。

另把取数命令写进 site/README.md，并注明「36 = 加载总数」这个易错点。
 2026-09-19 22:24:03 +08:00
JianFeeeee
fab27a1194 feat(site): 深浅双主题 + 动效层，并按用户要求移除立绘 
## 深浅双主题
跟随系统偏好，导航栏按钮可手动切换（存 localStorage）。首绘前在 <head> 里
定好 data-theme，无闪白（实测 reload 首绘即正确背景色）。
语义色全部令牌化，:root[data-theme="light"] 只覆盖取值；品牌三色两主题共用
（对应三层记忆，换主题不该换语义）。

## 动效层（1 → 11 个 keyframes）
极光漂移 + 细网格背景、粒子网络（近邻连线，密度按面积自适应、上限 72）、
三色滚动进度条、标题渐变流动、分块上错落入场、卡片聚光 + 3D 微倾、
三层记忆色条自上而下灌注、架构图流光带 + 节点脉冲、数字滚动到位、
分节标题下划线展开。

三条硬约束（都吃过亏）：
1. **内容默认可读** —— 初始隐藏只在 .js-fx 下生效，而 .js-fx 仅当 JS 真跑起来才加。
   实测 JS 禁用时 30/30 元素可见（旧版把 opacity:0 写默认样式里 → 26/30 永久不可见）。
2. **尊重 prefers-reduced-motion** —— 不启粒子、不画进度条、元素直接可见。
3. **装饰不得产生滚动条** —— canvas 改用 documentElement.clientWidth
   （window.innerWidth 含滚动条，实测多出 15px 撑出横向滚动），body 加 overflow-x: clip 兜底。

## 移除立绘（用户要求）
删掉 HTML/CSS/JS/资源/令牌全部痕迹，Hero 改单栏。README 记下为什么最终不放图：
原图是不透明 WebP（mode=RGB 实测），白底与角色白裙子同色，flood-fill 会渗进轮廓
让约 42% 身体透明 —— 这类素材要么出透明图，要么就别放。

## 顺带修掉 3 个真 bug（都是主题化后暴露/复核出来的）
1. **代码块换行全丢** —— .code 缺 white-space: pre，实测整段命令挤成一行。
   （这个 bug 在我这次改动之前就存在）
2. **浅色下导航看不清** —— header 背景硬编码 rgba(11,16,32,.78)，改用 --nav-bg。
3. **浅色下立绘处有灰块** —— .mascot::after 硬编码深色，改用 --mascot-fade
   （该规则已随立绘一并删除）。
另把 .badge / .btn-ghost:hover / 按钮光泽里 3 处 rgba(255,255,255,…) 令牌化为
--hover / --sheen，否则浅色下是白压白。

## 验证（共享 Chromium 实跑）
深/浅首屏 + 记忆段 + 架构段截图逐张看过；console 错误 0；坏图 0；
JS 禁用 30/30 可见；reduce 全可见且粒子/进度条已停；主题切换 → 刷新后保持；
390/768/1440 三档横向溢出均为 0；CSS 花括号平衡、8 个 keyframes 无孤儿。
 2026-09-19 21:49:59 +08:00
JianFeeeee
923d5d595f feat(site): 新增产品官网落地页（单文件 · 零构建 · 零外部依赖） 
用户要求写一个官网介绍页面。做成纯静态单文件，与仓库 WebUI 的既有做法一致
（原生 HTML/CSS/JS，无打包步骤）。

## 内容（每一条都对着源码/运行实例核实过）
- Hero：一句话定位（常驻型个人 Agent 框架）+ 看板娘立绘
- 四个设计决定：内核零 IO / 插件独立进程 / 输入有级别 / 忙时有人顶班
- 三层记忆：Context → Document → Graph，含媒体一等节点、描述即语义记忆、统一多模态空间
- 架构：一条消息进来之后的完整路径图 + 核心组件表
- 数字（**实测值，非估算**）：36 外部插件 / 340 工具 / 110k Go 行 / 10 LLM 适配器
- 上手命令、插件徽章墙、6 条 FAQ、页脚（文档/深入/项目/状态）

## 两个设计决定，都有理由
1. **配色取自品牌指南**：蓝/青/金正好对应三层记忆，故三层记忆那节直接用三色做色条。
2. **立绘按「有意的圆角卡面」呈现，不抠图**：原图是白底 + 蓝紫渐变外框，
   而白底与角色的白裙子同色 —— 连通域分析显示 flood-fill 会让 42% 的身体变透明
   （围裙、发丝高光被吃掉）。改为圆角 + 发光边框 + 底部渐隐，方形图与深色页自然衔接。

## 修掉一个真实的可访问性缺陷
初版把 `opacity:0` 写在**默认样式**里、由 IntersectionObserver 加 `.in` 揭示。
实测：30 个 .reveal 元素里 26 个停在不可见 —— **JS 被禁用或报错时整页永久空白**。
改为渐进增强：内容默认可见，仅当 JS 真跑起来才加 `.js-reveal` 接管动画。
复测两种场景均 30/30 可见（正常滚动 + 禁用 JS）。

## 验证（用共享 Chromium 实跑，不只是看代码）
- 控制台错误 0；两张图均加载（logo 400x400、立绘 1024x1024）
- 移动端 390px：无横向溢出，导航折叠，立绘置顶
- FAQ 手风琴展开正常（open=true）
- a11y：图片 alt 齐全、单一 h1、lang=zh-CN、无空文本链接
- 标签配对全 OK；34.6 KB；**无任何外部依赖**（无 CDN/字体/JS 库）
 2026-09-19 21:15:00 +08:00