|
|
255c799a40
|
feat(adopt): 邮件可投进平台上已存在的会话（TUI 与邮箱同一入口）
人在平台界面（pi TUI / opencode / DSH GUI）里开的会话，此前无法被邮件投进去。
补全早就把它们列为候选（agent_platform_sessions 镜像，插件心跳上报），
但投递侧的 FindNamedSessionFor 只查 sessions 表 —— 选中后只能得到 404。
候选列表在承诺一件做不到的事。
TUI 与邮箱是同一个 Agent 的两个入口，不是两套隔离的世界。
## Gateway
sessions 表加 platform_id 列 + 部分索引。resolveTarget 的 SessionNamed 分支
本侧查不到时再查镜像，命中则「接管」：本侧建一条会话并绑定 platform_id，
之后每次投递都在 SSE 事件里带 platform_session_id。
- FindPlatformSession(agent, slug, workspace) 查镜像
- FindSessionByPlatformID 防重复接管（一条平台会话只能被接管一次，
否则同一条对话在邮箱里裂成多条互不相干的线索）
- AdoptPlatformSession 建会话 + 绑定 + 别名复用平台 slug（撞名自动加后缀）
- PlatformIDOf 供 notifyRecipients 读
三处语义决定：
- workspace 以平台会话为准（它的 cwd 创建时就定了）。地址 path 位不同则不命中，
否则邮件会投进另一个项目的会话
- 主题优先用平台侧标题（它代表整条对话在谈什么，也是补全里显示的）
- 接管计入 AllowNewSession 速率限制 —— 镜像里可能有几百条 slug，
不计的话它是绕过限流的后门
## 插件
字段解析与失败话术抽成共用模块 lib/adopt.js（三方逐字节相同 + 进同源校验）：
字段名各写一遍时少个下划线就静默退化成「每封邮件新开一条」，而那个错误不抛异常。
- opencode：session.get 确认存在 → 照常 promptAsync（服务端持有会话，单一写者）
- DSH：复用 startAgent 的 resume 分支，会话 id 换成平台自己那个；
界面上正开着时直接 followup（两个 handle 会各自写日志，replay 过不去）
- pi：SessionManager.open(file) → 跑一轮 → dispose，不放进长期缓存
pi 必须短暂持有：SDK 无任何锁机制（flock/lockfile 命中 0），活着的
SessionManager 不 watch 文件 —— 外部追加的行看不见，算出的 parentId 指向
对方不知道的 entry，会话树分叉。写入是纯 append 所以文件不会坏。
配套三处：isStreaming 时不释放（否则杀掉排队中的下一封）、兜底计时器
（轮次超时 ×2，unref）、接管会话跳过命名同步。
最后一条是实测撞出来的：别名撞名时 Gateway 加后缀，而定稿别名又回写进 pi
会话文件 → 下次心跳上报的 slug 变成带后缀那个，人从补全里选的名字凭空消失。
opencode/DSH 无此环（它们的 slug 只读不写）。
接管后必须加入 mailDriven 集合，否则邮件投进去了却永远没有回音。
## 迁移顺序
idx_sessions_platform 不能写在 init_sqlite.sql 里：那个脚本在
addMissingColumns 之前执行，而已部署的库里 sessions 表已存在
（CREATE TABLE IF NOT EXISTS 不补列）→ 索引建在不存在的列上，
整个迁移中断、服务起不来（生产实测）。依赖补出来的列的索引一律放
migrate.go 的 sqliteAddIndexes。PG 侧用 ALTER TABLE ADD COLUMN IF NOT EXISTS。
## 生产验证
- pi × 2（agent-only-chain / mail-probe-alias）、opencode（glowing-moon）、
dsh（查看工程与插件适配指南）四条链路接管成功
- dsh 那次回信准确说出了界面上聊过的内容 → 上下文确实装回来了
- 第二封复用同一条本侧会话，平台侧无新增改名条目
- 回归：opencode 普通 .new + 别名续谈 + used_rounds=0（免配额通道未受影响）
## 其他
pi-mail-bridge 补 systemd 单元（此前是 setsid 裸进程，重启机器不会拉起）：
陈锁清理 ExecStartPre、MemoryMax=4G、TimeoutStopSec=10。
配置目录必须与 opencode 分开（共用会让后起的读到对方密钥或撞单实例锁）。
PLUGIN-CONTRACT.md 加 B-3.7 / B-3.8 + new_mail 字段表 + 检查清单验收项。
测试：repo +10 例（adopt_test.go）；三插件各 +7 例（adopt.test.mjs）
|
2026-09-04 11:14:44 +08:00 |
|
|
|
e4052f8e84
|
docs: B-8 在 HomeAgent 上是 N/A（平台无审批环节），补齐平台矩阵第四列
B-8 的 homeagent 那格一直标着「❌ 要先摸清 homed approval API」。
查清了：**那个 API 不存在，而且不该存在。**
判据：SDK 与核心两处 grep `approval|consent|permission|confirm`，
命中数均为 0。
前置条件是「平台本来就要问人」。另三个平台各有一个现成的审批环节
（opencode `permission.ask` / DSH `approval/request` / pi `tool_call`），
桥做的只是把它从本地 TUI 改道到邮件通道 —— 没有发明审批协议。
HomeAgent 的核心是纯思维核：本身无对外交互能力（全部能力来自插件），
也没有会话这一层（单事件循环）。它不问人，工具调用直接执行。
它确实有 `StageBeforeToolcall` 可以拦下调用（`process.go:273`，插件给
`ctx.Response` 赋值即拒绝，核心把「工具 X 已被插件拒绝」喂回模型）。
但那是「插件可以否决」而非「平台在征求同意」：没有待批准的请求、
没有选项、也没有等人的语义。
所以 B-8 是 N/A 而不是待办。硬补等于给平台加它本来没有的能力 ——
要自己划高风险工具白名单、自己定义超时与 fail closed、自己决定人不在时
怎么办，那些是产品决策不是契约合规。
顺带记下一个需要知道的事实：homeagent 的工具全部无条件执行（含 cmd_run），
接入邮件之后任何能给它发信的人或 Agent 都能间接触发，中间没有人类确认。
另三条链至少有 409 兜底，这条没有 —— 因为它根本不发起询问。
这不是缺陷而是那个平台的信任模型（homed 跑在用户自己机器上，默认完整权限），
记下来是为了让「谁能给 homeagent 发信」被当作访问控制来对待。
平台差异对照表补齐 HomeAgent 一列（14 行）。它是四平台里唯一**不需要**
为每封邮件开平台侧会话的：没有会话概念，所有邮件注入同一事件循环，
靠 output_send__agentmail 输出通道送回复。
|
2026-09-04 09:11:43 +08:00 |
|
|
|
bca50b80c6
|
docs: 日历子系统 + 寻址发现工具组 + 权限死锁的排查记录
PHASE7-REMAINING 新增日历一节：三层分离的理由、修掉的六个真问题
（含每一个的现场取证与判据）、前端三个易错点、验证清单、未做的缺口。
写成「可核对的规格 + 踩坑理由」而不是叙事：这些 bug 的共同点是
**不报错**（模板烤死时间、{time} 渲染成 UTC、每 tick 重发、附件从未落盘、
TRIGGER 往返断开、PG schema 缺表），下一个人只有知道判据才能避开。
README 把插件工具表从「六个」更新到十一个（现在 homeagent 是十五个），
并说明寻址发现那一组解决的是**猜地址** —— 生产上真的发生过一个 Agent
猜了 opencode@/home，投递成功但那不是它的工作目录，那封邮件静默变成了
一条平行会话的开端。
PLUGIN-CONTRACT 补 B-8（权限询问转邮件）的判据表与三平台差异。
|
2026-09-04 06:30:56 +08:00 |
|
|
|
e6fd2fafdc
|
feat: agent 邮件寻址能力全面补齐 + .new 别名替换
## 别名替换（让 .new 邮件可寻址）
repo/autoalias.go: AutoAliasFor + EnsureSessionAlias
- .new 建完会话立刻给别名（形如 dsh-重构导入路径）
- 名字与主题都要：只用主题跨 Agent 撞名，只用名字看不出聊什么
- sanitizeAliasPart 只留 unicode.IsLetter/IsDigit，其余折 -
- 撞名追加 -2/-3，全占用退 session-<uuid前8位>
- 不复用 SyncSessionAlias：那个假定已存在且跳过 manual
- 条件写入 WHERE alias IS NULL OR ''，并发安全
- resolveTarget 的 .new 与默认会话两条路径都调
notifyRecipients 加三个字段（每个收件方拿到自己那个地址的版本）：
- session_alias / reply_address / self_address
- 别名为空时退回省略 session 位，绝不写 new
FormatAddress(name,path,session) 空 path 也必须留 @ 与 .
## Agent 侧寻址发现（五个只读端点）
handler/agent_discovery.go:
- /agent/contacts + /agent/contacts/suggest（三段式补全）
- /agent/mail/{id} + /agent/mail/{id}/thread
- /agent/sessions/{id}/participants
- 不复用人类路由：scope 不同、审计需求不同
- 一律只读：归档/改名/权限决策仍只有人能做
repo/participants.go: SessionParticipants 逐封扫 from/to/cc
- Roles 用集合、MailCount 只数发信（0=还没开口的人）
- 发件人 path 不取 from_workspace（那列存的是 Agent 名）
repo.SuggestPaths 重写：mails.to_workspace（按 MAX(created_at) 倒序）
+ agents.workspaces 并集。原只读 workspaces，官方插件传 [] 永远空
## 共用模块（三插件逐字节相同）
lib/addressing.js: formatAddress/roleOf/replyAddressFor/selfAddressFor/participantsOfMail
lib/discovery.js: renderNameSuggestions/renderPathSuggestions/renderSessionSuggestions/
renderParticipants/renderContacts/renderThread
lib/inbox-format.js: renderMail 新增收件人/身份/可投递地址三段
- selfName 参数（兼容旧调用不传的情况）
check-shared-libs.sh 纳入 addressing + discovery
## 插件侧
opencode: suggest_address + list_contacts + session_participants + read_thread + read_mail
dsh: 同上 + forward_mail（此前只有 opencode 有）+ upload_attachment 改真 multipart
pi: 同上（createMailTools 加 agentName 参数）
dsh: ctx.agents.create id collision 改为 readSession 探测后 resume
dsh: 关键路径日志改 console.error（ctx.logger 不进 journalctl）
## 测试
repo: autoalias_test.go 11 + participants_test.go 7 = 18 例
plugins: addressing.test 17 + discovery.test 23 + inbox-format.test 31 = 71 例
go test ./... + npm test（opencode 155 + dsh 173 + pi 199）全绿
端到端验证：admin 发 dsh@....new 抄送 opencode@....new
→ dsh 用 session_participants 取到地址 → send_mail 给 opencode
→ 地址取自工具返回值（.crisp-planet），未手工拼写
|
2026-09-03 12:09:12 +08:00 |
|
|
|
22ddb1b89c
|
docs: 契约补一条转发层依赖的坑（socat 需要 PartOf + Wants 两个方向）
DSH 的 LAN 转发在 2026-09-02 隐形挂了 9 小时：为验证离线补投重启 dsh，
dsh-lan.service 的 socat 被 Requires 带停后再没起来。
Requires 不含重启语义、PartOf 不含启动语义、单元自己的
WantedBy=multi-user.target 只在开机时生效 —— 三者缺一，restart 或
stop+start 之后就会出现「平台进程活着、loopback 通、外网全不通」，
而这个现象很难联想到转发层。
下一个平台如果也用 socat 暴露 loopback 端口会踩同一个坑，因此记进
第九节「部署环境的坑」。另附 SuccessExitStatus=143：被 SIGTERM 停掉是
正常路径，不加会在 systemctl status 里留一条红色 failed 掩盖真故障。
本机的 dsh.service / dsh-lan.service 不入库（dsh 是被接入方，不是本项目的
一部分），只把可复用的教训记进契约。
|
2026-09-03 08:22:41 +08:00 |
|
|
|
289f37f7fb
|
docs: PLUGIN-GUIDE 重写为 PLUGIN-CONTRACT（可核对的插件规格）
原 PLUGIN-GUIDE 是叙事式的「怎么做 + 踩过的坑」，读者要自己从散文里推断
「我到底必须做什么」。接第三个平台时这不够用 —— 尤其当照着实现的是一个代理。
改为规格式，编号可引用、强度明确标注、每条尽量给出可机械核对的判据。
旧文档的内容全部保留（迁进第八、九节），另补上原先没有的四类：
## 一、能力矩阵（新增）
回答「这个平台能不能接」。七项必需能力（C-1..C-7）加七项可选（C-8..C-14），
每项给出判据。附一个七问自检 —— 任何一问答不出来就先别写代码。
其中 C-4「轮次结束信号必须能区分成功与出错」在两次适配里都被漏掉过，
两次都造成「无效模型被判成成功」，所以单独标了出来。
## 二、行为约定（重写）
原先散在各节的要求收拢成一个状态机，按事件逐条规定：B-1 启动 / B-2 心跳 /
B-3 new_mail / B-4 permission_decision / B-5 轮次结束 / B-6 无法处理时回信 /
B-7 启动补拉 / B-8 权限询问 / B-9 关停。
## 四、降级语义（新增）
平台缺某项能力时的确切退化路径（D-1..D-7）。原文档只说了「可选」，
没说缺了之后该怎么办 —— 于是「不支持权限钩子」很容易被实现成
「提供 request_permission 工具补偿」，而那正是 I-1 反对的模式。
## 六、不变量与禁止事项（新增）
12 条 MUST NOT，每条附「违反会怎样」。这些是测试全绿、跑起来也不报错，
但行为就是错的那类问题 —— 例如拉取失败时传 [] 而非省略字段会清空服务端目录。
## 七、验收清单（新增）
八组可勾选项，每条给出具体命令：grep 自查禁止事项、sqlite3 查在线状态与
配额未被消耗、停插件发信再启动看补投日志。
## 核对过的事实
写完逐项核对了代码，不是凭记忆：
- 12 个端点全部在 main.go 里存在且方法一致
- 发信 9 个字段名与 sendMailRequest 的 json tag 一致
- 心跳响应 12 个字段名与 handler 一致
- 九个数字（30s 心跳 / 25MB 附件 / 20 次每小时 / 补投 5 封 / 快照 200 条 /
模型上限 10 / 目录上限 300 / 降级超时 60s / inbox 默认 5）都能在代码里找到出处
- 验收清单里的六条 sqlite 查询都在生产库上跑通
- 38 个编号无重复，18 处交叉引用全部有定义
引用同步：PLAN.md、PHASE7-REMAINING.md、API.md、README.md、
install.sh、check-shared-libs.sh。
|
2026-09-03 08:09:54 +08:00 |
|
