日期：2026-08-28 状态：已采纳（建立在 adr-016 的频道绑定之上）
adr-016 落地了频道 ↔ 仓库工作区的绑定（/init、克隆、模型/思考深度/安全 权限档、频道主题为唯一常驻信息面）。本篇是对话面，用户定的工作逻辑：
- 绑定频道里
@bot <问题>； - bot 以那条消息开一个子区（主频道保持干净，只见子区标题）；
- 子区里直接与 acp 对话——工作目录就是绑定的克隆，模型/思考深度/权限 档全部沿用绑定（/model /effort /access 随时可改）。
「不使用会话的一针一线」指的是会话体系（service 层的 Session/Chat/转录/
SSE）；internal/acp 是叶子协议客户端（与 gitrepo 同性质），discord 直接
import。但会话池独立（chatMaxSessions=4、轮超时 30 分钟、空闲 20
分钟回收）——与网页会话池互不挤占，discord 的资源边界自己管。agent 的
启动方式（命令/参数/环境）经 Deps.AgentRuntime 注入，包仍不认识
model/db。技能包注入与网页会话同一份（SkillpackDir）。
子区本身就是完整的对话记录，不进 acpp 的转录体系、不在网页会话列表出现。
唯一落盘的是 threads（子区 id → acpSessionId，存 discord.json）：子进程
被空闲回收或服务重启后，凭它 session/load 无感恢复上下文。
回合进行中的追加消息排队，当前轮结束后合并成下一轮输入。刻意不用 acp 的 Interject——它在两个 runtime 上语义不同（claude 排成独立新轮、 codex 注入当前轮），排队的行为可预期且实现只有一把锁。
思考、工具调用、计划都不发（频道干净原则）；回合期间用 typing 指示器
（8 秒续一次）表达「在干活」。轮末把正文按 1900 字分段发出，代码围栏被
切开时每段补闭合、下段重开。纯工具轮（没有正文）发一行结束原因。
/stop 中止当前回合并清空排队输入。
- 权限申请 = 按钮裁决卡：选项直接是按钮（allow 类绿、reject 类红）， 点一下即裁决、卡片原地收口（✅/❌ + 由谁 + 时间）；claude 的计划审批 （PlanReview/ExitPlanMode）同一张卡，计划全文进卡片正文。回复选项编号 的文本快捷路径保留。
- 提问 = 一次性表单（第四轮迭代定稿：逐题卡「反复和服务器通信」被
否，用户拍板「一个表单操作完成全部选择」）：入口卡列出全部题目 +
「📝 填表回答」按钮，点开一个 modal 全部答完一次提交。每题占一个
modal 组件——多选 CheckboxGroup(22)、单选 ≤10 项 RadioGroup(21)、
更多 String Select(3)、纯输入 TextInput(4)；带「其他」的题在其正下方
紧跟一个可留空的输入框（问题→选项→输入的排布是用户点名的）。多选/
单选的判定来自 requestedSchema 实测形状：多选是
type:"array"+items.anyOf，单选是顶层oneOf（与 web 端 lib/elicitation.ts 同一 口径）。modal 一屏最多 5 个组件，claude 单次最多 4 题——常态一页装完，5 题才分页兜底（提交后经「继续填写」按钮翻页）。提交即收口：入口卡 原地变成逐题「✅
题答案」的记录卡，不再发多余的确认消息。单题 提问直接打字回答也有效。 - 组件 custom_id 带随机 nonce，旧卡的残留按钮点了只会得到「已失效」， 不会误触当前问答。问答在别处（网页/超时）收口时，卡片改灰终态 （PermissionDone/ElicitationDone 事件驱动）。
- 每子区同时最多一个挂起问答（ACP 语义如此：权限/提问挂起在 prompt 调用之内，同一会话不会并发多个）。
- 消息附件进入对话：附件一律先落盘到
<workdir>/.acpp-uploads/（agent 能移动、改名、当素材用），目录登进.git/info/exclude不脏 仓库。内容块按类型追加：图片双发 image block + resource_link，≤32KB 文本内嵌全文（与网页 @ 文件同口径），其余 resource_link 按需读。 纯附件消息（无文字）也能开子区/进对话。 - 任务计划卡：agent 的 plan 更新渲染成一回合一张、原地 PATCH 刷新 的 V2 卡（✅ 划线 / 🔄 加粗 / ⬜ 待办），回合结束卡上即终态，历史回合 的卡留档；generation 计数防晚到的旧状态盖掉新状态。
- 工具面与网页会话同源：数据库工具面（datasource）按项目有条件挂，
报告工具面（report）无条件挂。凭证走
mcp.PeerTokens非会话通道—— 绑 (子区 key, workdir) 存内存，进程重启失效、开会话现领；HandleMCP 先查它再查会话表，观测记录 sessionID 记 0。report_open 的打开事件按 子区 key 路由回 discord：子区里发报告卡（标题 + 路径 + 「打开预览」 链接），预览走GET /api/discord/reports/{channelId}?path=…（软链 解析后必须落在绑定工作目录内、只放行 .html、CSP sandbox）。
- markdown 转译：agent 回复是标准 markdown，Discord 只认小方言。
发出前转译（
mdToDiscord）：表格→等宽代码块（CJK 按 2 宽对齐）、 ####+ 标题→加粗、- [ ]/- [x]→☐/✅、---剔除；围栏代码块内 原样不动。 - @bot 的集成角色也算 @bot：自动补全里 bot 用户和同名集成角色并排，
选到角色时
mentions是空的（<@&roleId>在mention_roles）， 之前完全不响应（真机踩坑两次）。现按 guild 查tags.bot_id指向 自己的角色并缓存。 - 数据库工具面按需挂载：常挂会诱发「平时问答也去查库」（用户反馈），
改为默认不挂：
/db on|off|status显式开关，消息里带@db/@数据库令牌一步开启（令牌不进 prompt）。切换即关旧会话，下一轮凭 acpSessionId 无感恢复并带新挂载；开关按子区落盘（Thread.DBEnabled）。 - 权限收口卡压成两行：决策完成后不留命令全文（用户点名嫌大）， 只留「✅ 选项 · 对象截一行 · 谁批的 · 何时」。
- /help：完整用法卡（@ 对话/附件/数据库/报告/命令表），仅本人可见 且不自动删；打成纯文本的裸斜杠命令（/help 等）不进对话，回小字提示。
- 工具活动卡：与计划卡同模式——一回合一张、原地刷新，✅/🔄/❌ 逐行列最近 8 条工具调用（更早折叠成计数）；渲染结果没变不 PATCH。
- 回合小结：干过活的回合在回复末段附「-# ⏱ 耗时 · 🔧 N 次工具 调用」；<20s 且无工具的快问快答不带尾巴。
- 排队消息可编辑：还挂着 ⏳ 的消息编辑即生效（MESSAGE_UPDATE 更新 队列文本），已进对话的编辑不追溯也不提示。
- 权限收口两行小卡 与 @db 按需数据库（§7）同场验证：自然业务 提问（不点名工具）下 agent 能自行发现并正确使用 db_* 工具。
网页会话消息流逐项对照后的取舍：
| 网页会话元素 | discord 形态 |
|---|---|
| markdown 正文 | md 转译（§7） |
| 工具调用卡 | 工具活动卡（§8），edit 类的文件收进回合小结 ✏️ 计数 |
| 计划卡 | 计划卡（§6） |
| 权限/提问卡 | 按钮卡 + 一次性表单，卡上 @ 发起人（allowed_mentions 只放行 |
| 这一个人）——无人值守时「等你拍板」推送到手机 | |
| 报告 | 报告卡 + 整页长图直发（webshot 包驱动本机 Chrome 截图， |
| multipart 发进子区）。预览链接已拆除——指向本机后端的 URL 对不同 | |
| 局域网的用户点不开，长图是唯一展示形态 | |
| 附件 | 三口径进对话（§6） |
| 子代理归属 | SubagentOf 非空的过程输出不混进主回复，工具卡上有 |
| 子代理启动那一行 | |
| token 用量 | 回合小结 🧮（PromptResult.Usage.TotalTokens） |
| 思考过程 | 刻意不显示——频道里它只是噪音 |
| 消息编辑/回退 | 排队中编辑生效（§8）；带上下文截断的 rewind 待做 |
被一场真实事故定型：子区数据库面没挂载时，agent 找不到 db 工具， 竟试图 ssh 隧道直连生产库（被权限卡拦下三次），还想让用户手工 回贴 SQL 结果。三层防线：
- 挂载入口拓宽：主频道消息带 @db 令牌视同 @bot（此前被静默忽略， 用户以为 bot 挂了）；消息含明确意图词（数据库/数据源/表结构/SQL…） 自动开子区挂载——漏挂的代价（编数据/野路子）远大于误挂（多五条 工具描述）；/db 显式拨过的子区不再自动改（DBManual）。
- 场景提示词（acp 新注入口 OpenOptions.InstructionsExtra，追加在 基础提示词后，只对 claude 生效）：紧凑回复、长内容走报告，以及焊死 的一条——数据库面没挂载时禁止 ssh/mysql 任何野路子，指引用户挂载。
- db-query 技能（~/.acpp/skills/db-query）：正确的工具工作流 （先认环境再看结构、COUNT 不翻页、information_schema 行数是估算值）。
同场修掉消息队列两处丢消息（runThread 收尾竞态、问答挂起时非答案 消息被怼回丢弃），见 commit。
展示统一（用户点名「不要让对话区域看起来很乱」）：色彩语言定为 行动=蓝紫（权限/提问）、过程=灰（计划/工具）、成果=绿（报告/收口）、 错误=红；错误文案统一「emoji + 一句话 + -# 小字详情」；工具活动卡 回合结束收口成一行（全成功时；有失败保留明细供排查）；报告卡状态 行有生命周期（生成中→清除/失败原因），不再停着过期的「生成中」； 长图消息带归属小字。
send_file 工具面（acpp-chat，本包自家 MCP server）：agent 把生成 的文件直接发给用户——.html 经 webshot 渲染成整页长图（用户拍板「尽 可能给渲染后的」），图片原样发，其余当附件。回连端点 /api/mcp/discord/{token}，路径护栏与 ReportPath 同口径；场景提示词 补一条「贴路径用户什么都看不到」。MergeClaudeMounts 挪进 mcp 叶子包。
一场「肯定有 bug」的排查教训：/db on 后工具面死活不出现，先后误判过
dev 隔离、session/load 不装挂载，真凶最后靠日志取证钉死——重新 /init
后 workdir 命名带 @分支 后缀，projectCandidates 的候选变成
pp-game@main，数据源配置的项目名是 pp-game，项目过滤 rows:0，
挂载永远算出空。修：candidates 剥 @ 后缀补裸仓库名候选。教训入档：
先取证再改——凭现象推协议行为，两次都推错了。
同场拍板：子区默认挂载数据库工具面（DBOff 显式关）——按需挂载 试过一轮，「说数据库的事却没工具」的挫败远多于误查；意图词自动挂载 整套删除。防崩护栏加固：单条查询 30s 硬超时（行数硬顶挡不住扫全表的 慢查询）、超时错误翻译成可行动提示；db_query 描述与 db-query 技能写 明逐步查询纪律（先 COUNT、必带 WHERE/LIMIT、截断就收窄、游标不深翻）。 端到端验证：AI 按 schema → COUNT 聚合 → 边界 → 取样的顺序查完， 自发出了带图表的 HTML 报告长图。
MESSAGE_CREATE 不带 parent 信息，第一次见到的 channel id 现查一次 REST （结论含负缓存）。绑定频道下用户手动开的子区同样收养——判定标准是 「绑定频道的子区」而不是「bot 开的子区」。
用户在子区说「tmp/用户行为日报-20260831.html 发上来」，拿回的是一张
长图——send_file 把 .html 吃掉换成截图，原文件根本没出去。§11 那条
「尽可能给渲染后的」被执行成了「只给渲染后的」，而说「发上来」的人
要的是文件本身：能存档、能转发、能双击用浏览器打开（报告的交互与
主题只有原文件才有）。
拍板：长图是附赠品，不替代原文件。两条出口一起改：
- report_open 的子区落地：一条消息发两个附件——整页长图 + 原 HTML。预算按「HTML 先占」算（合计 24MB）：长图要靠本机 Chrome， 可能失败也可能很大，挤掉那份一定拿得到的文件去发图是本末倒置。 渲染失败/放不下只在报告卡的状态行说明，文件照发。
- send_file：
path换成paths（一次最多 10 个，单数写法照收 ——模型按「一个文件」的直觉传path的概率不低，为此报错纯属自找 麻烦）；.html 默认发原文件 + 长图，preview:false只发原文件； 渲染失败不算失败，降级成只发原文件而不是整个调用报错。
发送侧统一到 botRESTFiles（attachments 的 id/filename 预登记由它按
顺序补齐，调用方手写那张对照表只会写错），按 Discord 单条上限 10 个
附件 / 24MB 分批，只有第一条带说明文字。附件顺序上长图排第一——平台
只把首个附件渲染成预览大图。
配套：技能 send-file 进技能库（工具描述解决「怎么用」，技能解决
「什么时候该想起它」——用户开口要文件时，模型的第一反应往往是 cat
一遍文件把内容贴出来）。
§14 把「只发长图」修成「长图 + 原文件」，用户看完实物后给出了更准的口径： 报表不要长图，直接给一条点开就能看的链接，而「把 xxx.html 发上来」 这种明确要文件的场合照发文件。于是交付不再是一种固定组合，而是三种形态 按场景选——由 agent 判断，工具描述与 send-file 技能给判据：
| 形态 | 用户拿到什么 | 不可替代之处 |
|---|---|---|
file |
附件 | 能存档、能转发、能再编辑 |
link |
渲染后的页面 | 手机上点开即看，能选中文字、能展开折叠块 |
image |
整页长图 | 不出网、不依赖第三方 |
auto（默认）把 .html 判给 link、其余判给 file。报告（report_open）的子区
落地直接走 link，长图与原文件退成降级位。
外链选型（2026-08-31 实测）：gist 页面显示源码、raw 是 text/plain
（浏览器当纯文本），githack 系 CDN 会先插一张「One more step」确认页——
点链接看到警告而不是报告。最终用 gistpreview.github.io/?<id>：拿 GitHub
API 取 gist 再就地渲染，一跳直达，secret gist 匿名可读所以无需凭证。
上限卡 1MB 而非平台的 10MB：再大 API 会截断，链接打开是半张报告。
外链是有代价的，所以三件事必须齐（新包 internal/gist）：默认 7 天
失效、卡片上明写「拿到链接的人都能打开」、随时能撤销。用户点名要的收回
能力落成 revoke_link（传 id 或 all）与 list_links。撤销前先查描述
前缀确认是 acpp 发的——id 是模型给的参数，没有这道闸，一句话就能删掉用户
自己收藏的 gist。
状态不落盘：归属（子区 id）与到期时刻写进 gist 描述，进程重启、换台 机器照样列得出、撤得掉。过期链接靠 30 分钟一趟的清扫真正断开访问——有效期 是承诺，没人删就等于没有有效期。
用户报障「开始对话后无法主动停止」。/stop 从第一版就有，但操作人员不知道
——手册与 /help 都没提，斜杠命令列表里一条灰字说明没人会去翻。结论：
中止必须是子区里看得见、点得到的东西，不能只是一条命令。
- 工具活动卡改成过程卡：回合一开始就发（此刻只有「⏳ 正在处理…」一行）， 右侧挂 ⏹ 停止 按钮；工具调用照旧在同一张卡上原地刷新。这样会话启动、 长思考这些没有工具调用的阶段也有地方可停。收口时按钮一律摘掉：被中止 → 「⏹ 已由谁中止 · 🔧 N」；没干活 → 整张删掉（纯问答不留空卡）；有失败 → 留明细；全成功 → 压一行（不变）。
- 停止覆盖会话启动阶段：此前 /stop 只是 acp 的
session/cancel，prompt 还没发出去（握手、挂载 MCP 可能十几秒）时够不着，而且 runThread 已经把 这批输入从队列里取走，清队列也拦不住。现在每轮有自己的 ctx（beginTurn）， 停止 = cancel 通知 + 掐 ctx，握手提前退出按「已中止」收尾、不报故障。 - 按钮带回合代号：custom_id 是
st:<turnNonce>，旧卡残留的按钮对不上号 只回本人一句「这一轮已经结束了」，不会误停下一轮。 - 清掉的排队消息摘 ⏳：留着会让人以为它还会被带上。
- 顺手修掉一个老 bug：过程卡状态（toolLog / toolMsgID / touched）跨回合没
重置——第二轮会去改第一轮那张卡，回合小结里的工具计数与改动文件数也在
累加。现在由
beginTurn每轮清零。 - /help 与频道手册各补一行「停下来」。
- gateway intents 加 GUILD_MESSAGES + MESSAGE_CONTENT（特权 intent， 开发者门户已开）。
- 主频道的非 @ 消息一律不响应；未绑定频道的 @ 同样沉默。
- 子区里 @ 了别人（用户、角色、@everyone/@here）却没 @ bot 的消息视为 人与人的旁白，不进对话（真机报障：「@同事 看下报告」被 bot 回了一轮）； bot 一起被 @ 到才照常入队。
- 绑定改仓库后，已开的子区会话仍在旧 cwd 上（会话粘住打开时的目录）； 子进程回收后的下一轮才落到新目录。可接受——重绑是低频动作。
- 单条回合上限 30 分钟（含挂起的问答），超时按失败回报。