diff --git a/docs/maintainer/handoff-2026-09-16.md b/docs/maintainer/handoff-2026-09-16.md index c7d2f24c4e..90ddeb8ed2 100644 --- a/docs/maintainer/handoff-2026-09-16.md +++ b/docs/maintainer/handoff-2026-09-16.md @@ -1,4 +1,6 @@ -# Handoff —— 2026-09-16（自动合并通道、provenance 门禁、四个工作流立项与在途） +# Handoff —— 2026-09-16 → 09-17（六个工作流全部落地：门禁、自动合并、收养、命中率、报告卡口、结构化字段、企业部署） + +> **更新于 2026-09-17 上午**：全部在途项已合并，0.5.4 已发布，生产端已做首次中文检索验证。§3 与 §7 已按最终状态改写；§8 是新增的生产验证记录。 > 面向下一个接手的人（或下一个 session）。本文件只写**当前事实 + 需要人决定的事**，不重复设计文档。 > 相关文档：`docs/maintainer/blueprint-and-strategy-review-2026-09-16.md`（战略审视）、 @@ -31,23 +33,27 @@ 外部：`@misaka-net/misakanet-setup@0.5.3` 已发布；个人站点与 profile README 已更新（含新 blog《Five Failures That Passed Every Check》）。 -## 3. 在途 +## 3. 全部落地（原「在途」章节，09-17 收口） + +七个工作流全部合并进 `main`（`main` = `8d362241a` 起），我方**无开放 PR**： -| 项 | 状态 | -|---|---| -| **#1786** `/adopt` fork 收养流程 | PR 开着，等 CI 绿合并（18 项测试；dry run 已对真实 PR #1656 跑通） | -| **#1787** 语音钩子 → 注意信号路由 + 桌面通知 | PR 开着，等 CI 绿合并（28 项测试；cue 只作查表键，命令全部是文件内字面量） | -| **#1788** 自动合并通道的 403 热修 | PR 开着（`gh api user` 用 App token 必然 403；已改常量 + `gh_read` 防御 + 作业级 `continue-on-error`） | -| **#1779** 命中率分母 | Agent 已完成，**待整合**：与 #1783 在 `workers/register-proxy-sw.js` 里交错 | -| **#1782** `--report --strict` 卡口 | Agent 已完成，**待整合**：与 #1783 在 `packages/misakanet-setup/bin/misakanet-setup.mjs`、`workers/misakanet-setup.test.mjs` 里交错 | -| **#1783** 结构化课程字段（`summary_plain`/`trigger`/`verify`） | Agent 仍在跑（最后一个） | -| **#1780** 接线近义词表 | 排队：等 #1779 合并（同文件另一区域） | -| **#1784** 企业部署 `--silent`/`--report-json` | 排队：等 #1782 合并（同文件） | +| 项 | 落地 | 关键点 | +|---|---|---| +| **#1779** 命中率分母 | 已合并 | 新 D1 表 `search_signals`（命中与未命中同一段代码、同一套字段）；`GET /api/search-signals/stats` 只回 `solved`+`created_at`；`MISAKANET_SEARCH_SIGNALS=0` 可停 | +| **#1782** `--report --strict` 卡口 | 已合并 | 0/1/2 退出码；默认 `--report` 仍退 0（贴给人看的用法不被破坏）；人手填的 `tools-visible`/`live-call-evidence` **永不**参与判定 | +| **#1783** 结构化课程字段 | 已合并 | `summary_plain`/`trigger`/`verify`（新增课程强制、存量劝告）；对无字段的老课程响应**逐字节相同**（sha256 证明） | +| **#1784** 企业部署 | 已合并 | `--silent` + `--report-json`（同一数据模型两种编码）+ GPO/Intune/Jamf/Ansible + **数据边界**（明写托管端点无自托管形态，给出本地 stdio 替代与其代价）；**0.5.4 已发布** | +| **#1778** fork `/adopt` | 已合并 | dry-run 默认、两段式评论、`Co-authored-by` 保 credit、`origin` 守护（拒绝把自己推进 fork） | +| **#1785** 语音 → 信号路由 | 已合并 | 一张 cue→动作表；命令全部是文件内字面量（cue 只作查表键）；`MISAKANET_NOTIFY=0` 只关通知 | +| **#1780** 接线近义词表 | 已合并 | worker + 本地 CLI 同表同开关；统一旧 `_SYNONYM_MAP`（30 条迁移为 `related` 降级层）；`INDEX_TEXT_VERSION` 保持 3（查询期展开，索引文本未变） | +| 门禁 / 自动合并通道 | 已合并 | #1768/#1771/#1773（含门禁自身 SSRF、令牌外泄、开放重定向的修复）+ #1781/#1788（403 热修） | -**整合方式已定**：#1783 落地后，把三者的改动**按 hunk 拆开**，各自开 PR、各自跑测试，不把三件事塞进一个 PR。 +**整合方式（下次照做）**：并行 Agent 改同一文件后，用 `git apply` 按 hunk 过滤拆开（`/tmp/split_hunks.py` 的做法），各自开 PR、各自跑测试；第三个拆分用**独立 worktree** 而不是在主工作树里切分支。 ## 4. ⚠️ 需要维护者（人）介入的事 +> 09-17 更新：下面第 4 条（PAT）**不需要做**才能用 `/adopt`；`auto-merge-lesson` 标签**已创建**；第 1、2 条（首次 `/adopt`、首次自动合并）仍未发生，是整条机械通道唯一没跑过的环节。 + 1. **`/adopt` 的首次真实使用**：#1746–#1750 五个课程 PR 的内容是好的，只缺 DCO 签核（fork PR 的机器人推不动）。流程是：等 #1786 合并 → 在其中一个 PR 上评论 `/adopt`（看计划）→ 再评论 `/adopt --apply`。 **不要收养 #1656**：它是 519 字节骨架，课程本身过不了结构门禁，收养只会把一个本该被拒的 PR 合并进来。 2. **首个自动合并的端到端验证**：收养产生的新 PR 是同仓分支、签核齐备、只改 `lessons/`，**正好可以打上刚创建的 `auto-merge-lesson` 标签**，验证 #1781 的通道真的能自己合并。这也是目前唯一缺的"通道上线但没跑过"的一环。 @@ -72,9 +78,39 @@ 4. **门禁必须被对抗性地读一遍**：provenance 门禁当天就被 open-code-review 找出三个安全洞；`too_large` 会跳过最大的文件（`workers/register-proxy-sw.js` 4475 行已切片补扫，结果在 issue #1775）。 5. **只在有证据时失败**：超时/DNS/限流/5xx 一律记 `unknown` 且不让构建变红——否则门禁一周内就会被绕过。 +6. **共享工作树里不要用 `git checkout -- ` 去"取一份干净版本"**。我在拆分 PR 时对 `workers/register-proxy-sw.js` 这样做，把另一个 Agent **尚未提交**的改动从工作树里抹掉了（它自己又逐处重打了一遍）。已提交到分支的内容没丢（动手前先备份了完整文件与 patch），但这条动作在任何"多 Agent 共享 checkout"的场景里都是危险的：**要干净版本就用独立 worktree，或从 `git show :` 取；永远不要就地覆盖别人正在改的文件。** +7. **"部署成功"≠"行为已生效"**。worker 的 `deploy-worker.yml` 报 success 只说明推上去了；真正的验收是在生产端点用真实查询验证（§8）。同理，"发布成功"的判据是发布任务日志里的打包版本，而且本机可达的镜像可能还在同步上一个版本。 + ## 7. 建议的下一步（按顺序） -1. 合并 #1786/#1787/#1788；#1783 落地后按 hunk 整合 #1779/#1782/#1783。 -2. 启动 #1780（接线近义词表，统一 `misakanet/search/engine.py::_expand_query` 的旧 `_SYNONYM_MAP` 与 `data/query-aliases.json`）与 #1784（企业部署）。 -3. 用 #1746–#1750 之一跑通"`/adopt` → 打标签 → 自动合并"，把整条机械通道验成事实。 -4. worker 部署后确认 `/api/search-signals/stats` 有数据；有分母之后再评估 B1。 +1. **维护者两件事**（见 §4）：用 `/adopt` 收养 #1746–#1750 之一并打 `auto-merge-lesson` 标签跑通机械通道；带 token 复验生产（§8 给了命令）。这两件做完，"课程生产线"才算**端到端**被验证过，而不只是各部分各自绿。 +2. **等分母有数据**：`/api/search-signals/stats` 有了样本之后，才算得出命中率，也才能评估 #1767 里 P2 的 B1（首次报错自动触发）。在那之前做 B1 是无法评估的。 +3. **#1780 的两个尾巴**：FAQ 匹配器是否跟随展开；`trigger` 是否并入 BM25 索引文本（并入需要 bump `INDEX_TEXT_VERSION` 并承担一次全量重建——要把这个代价和收益一起评估，别顺手做）。 +4. **#1713–#1716 的处置**：改一行 provenance 即可合并；对方不响应时决定关闭还是补写。 +5. **零散但值得**：`workers/register-proxy-sw.js`（4475 行）的 ocr 切片扫描结果在 issue #1775，其中 6 条已核实的严重项仍待认领（freshness 列表解析、heal.py 写原始日志、remote.py 路径拼接等）。 + +--- + +## 8. 生产验证记录（2026-09-17 上午，首次） + +`#1794`（接线近义词表）合并后 worker 自动部署成功（deploy-worker run 143 @ `8d362241a`），随即在生产端点 `https://misakanet.org/mcp` 上验证： + +| 查询 | 结果 | 读法 | +|---|---|---| +| `如何切换识图模型` | ✅ **2 条命中，top = 《多模型Switch脚本模式 — 双 Agent 模型管理》** | 这句纯中文问句在接线前返回 **0 条**。**这是 #1794 的验收点，已达成** | +| `定时任务不执行` | ⚠️ 有命中（2 条）但 **top 是错的**（GBK 编码那篇，不是 cron 那篇） | 别名给的是**召回**，不是这个句式下的精度；与评测中"仍有 4 条失败"一致 | +| `switch vision model` / `如何切换视觉模型` | ❓ `no_match=False hits=0` | 与**匿名配额（5 次/天/IP）被本轮探测用尽**的表现一致；改用本机 token 复验时 `misakanet.org` 出现 TLS 握手超时（本会话反复出现，属网络抖动），**未判定** | + +**下次复验请带 token**（本机可用：`/tmp/pub-cc/.misakanet-agent/token` 或安装器写入的 `~/.misakanet-agent/token`），并顺手确认： + +```bash +curl -sS "https://misakanet.org/api/search-signals/stats?days=7" | python3 -m json.tool # 期望 200 + rows 非空且在增长 +curl -sS https://misakanet.org/mcp -H 'Content-Type: application/json' -H 'Accept: application/json' \ + -H 'MCP-Protocol-Version: 2025-06-18' -H 'Origin: https://misakanet.org' \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"misakanet_search","arguments":{"query":"定时任务不执行","top":2}}}' +``` + +**不要把"两次无法判定"写成通过**——这一轮已经因为"绿灯掩盖真红"付过代价（见 §6）。 + +**仍未做的**：`#1780` 的 FAQ 匹配器没有跟着展开（阈值语义会变，离线评测看不到 FAQ 语料）；`trigger` 尚未并入 BM25 索引文本。两条都写在 `docs/maintainer/query-alias-design-2026-09-16.md` §8.7。