Advisor 顾问(advisor)
一句话:主会话每跑完一轮,自动叫一个你手动指定的模型来看一眼全局走向,给分级建议——它不是 sub agent,不用你派,按节拍自己出现。
0. 何时用 / 何时不用
- 用户说「帮我盯着 / 每轮把关 / 把控全局走向 / 开个顾问 / 每轮有人 review」→ 用本技能,先走第 2 节的面板启用三步。
- 用户说「advisor 面板打不开 / 开了没生效 / 没指定模型 / 一条意见都没有」→ 用本技能走第 6 节排查顺序。
- 不需要「每轮都要有人把关」的轻量任务(改个措辞、查个文件、跑条命令)→ 不要开,理由见第 5 节的成本口径。
- 想让 sub agent 干活(派角色、派任务、指定交付物)→ 不走本技能,走
agent-workflow-router/agent-general-route。
1. 这是什么:被动机制、无工具面
advisor = 每个 turn 结束后自动调一个模型,给主会话「把控全局走向」的评审机制。
| 维度 | advisor(本技能) | 三个派活工具(agent_roles / agent_taskbook / agent_spawn) |
|---|---|---|
| 出现方式 | 自己按节拍出现:turn 结束即评审 | 被叫来干活:先查角色、审任务书、再派 |
| 是不是工具 | 不是工具。全仓 tools.register 只有三处,正是上面那三个(lib/index.js 工具注册段的 agent_roles / agent_taskbook / agent_spawn) |
就是工具 |
| 有无工具面 | 宿主侧工具面为零——不占这三个工具位,也不设任何 advisor* 工具(advisor 内部的评审模型可持有只读检索工具做仓库分析——S3 agentic 循环;不占宿主工具位) |
工具面本体 |
| 上下文 | 自己的持续会话,继承主会话零上下文 | 靠任务书注入上下文 |
| 产出落点 | 分级建议,以用户指令口吻进入主会话(nit 及以上默认 steer 实时打断) |
sub agent 的产物按任务书交付 |
一句话区分:sub agent 是「被叫来干活」,advisor 是「自己按节拍出现」。想派活走派活工具,想把关才开 advisor。
2. 怎么用(走面板,不设工具)
没有 advisor* 工具,唯一入口是 Advisor 面板(挂 conversation.session.header.actions 槽位,lib/client.js 的 advisor slot 注册——id dsh-agents-advisor):
- 开面板:目标会话的会话头部动作区有个 Advisor 胶囊(可拖动、位置持久化),点它打开右侧停靠面板。
- 选模型(先做这步):面板「评审模型」区选
provider与model→ 点「保存模型」。 来源 chip 必须从「未指定(该会话不评审)」变成「本会话手动指定」。 - 启用:勾选「为本会话启用」。
- (可选)「立即评审一次」不等下一轮,直接补一次评审。
顺序不能反:「为本会话启用」复选框在未选模型时是禁用的(tooltip:「请先在下方为本会话选择评审模型(开启必须同时指定模型)」,lib/client.js 的启用复选框禁用逻辑,tooltip 文案即锚)。先勾启用再补模型,第一发会被服务端 400 挡回。
面板上还能看到:运行状态(disabled/idle/reviewing/error)、队列长度、上次评审时间、按严重度排的评审记录。
3. 三条不可跳过的前提(用户拍板的硬语义)
3.1 模型完全手动指定、无任何兜底
- 只认该会话自己配置文件里的
provider/model(resolveAdvisorModel,lib/advisor/assemble/session-views.js——S5 起index.js只 re-export)。 - 不回落 HIGH 档、不读全局配置、不继承主会话模型。
resolveAdvisorModel历史上第二个入参就是 HIGH 档路由提供者,现已彻底移除。 - 不指定 = 该会话不评审:端点以
modelSource:'unset'如实说明,runtime.status='error'。 - 硬门禁在运行时也成立:未指定模型时
ensureRuntime直接返回undefined,绝不调模型。
3.2 advisorEnabled / advisorProvider / advisorModel 是废弃兼容键
三者的准确措辞是 deprecated / compatibility-only / does not affect runtime behavior(lib/advisor/index.js 的 DEPRECATED_ADVISOR_KEYS 常量注释)。
- 不要去改
cordis.patch.yml里这三个键——它们必须继续留在ALLOWED_KEYS:cordis.patch.yml随包默认带着它们,删掉成员会让「老配置里还在的键」触发「未知 advisor 配置键」而整个插件 boot 失败。 - 现在只被解析(保兼容,且绝不抛错)与一次性告警(条件:键存在且值与随包默认
false/null/null不同),不参与任何生效判定。 - 为什么不能只写个 deprecated 了事:配置里躺着一个看起来像开关、实际完全不生效的键,维护者极易据此把逻辑重新接回去。
3.3 每会话独立配置,落在自己的文件里
- 落盘路径:
<dataDir>/sessions/<base64url(sessionId)>.json,只落SESSION_CONFIG_KEYS声明的键(lib/advisor/store.js;现含enabled/provider/model/projectPhase)。 - 分文件而不是共用一个
config.json:多个会话可同时改配置,共用单文件要做「读-改-写」,A 读 B 写 A 写就会丢更新。 - 不扩展宿主 settings schema,不进
cordis.patch.yml,也不进宿主 settings;重启后仍生效。 - 写入走「读—判—写全程同步」的临界区(Node 单线程天然串行);
enabled:true必须同时具备provider与model,否则 400、零写盘(U2 成对规则,lib/advisor/store.js的writeSessionConfig)。 - 幂等 seen 集合另存
sessions/<b64>.seen.json,独立文件,不与配置争同一 inode。 dataDir默认锚在~/.dsh/plugins-data/dsh-agents/advisor(不随宿主 cwd 漂移)。- 旧版全局
<dataDir>/config.json:存在即忽略(不读、不迁移、不删除),但每次启动打一次告警——「我明明开了却没生效」多半就是它。
4. 已知边界(实测既定取舍,不是待修缺陷,如实列出不藏)
| # | 边界 | 事实与依据 | 后果 |
|---|---|---|---|
| 1 | sessionId 校验是 liveness check, not authorization |
宿主 WebRoute 只有 kind/path/handler,没有鉴权钩子,handler 拿的是裸 IncomingMessage;宿主自述原文「Ambient presence is neither liveness proof nor authorization」(lib/advisor/assemble/session-views.js 的 isActiveSession 注释,宿主原文在 dsh-agent 的 lib/types/index.d.ts) |
能关闭:不存在/已 dispose 的 sessionId → 404,PATCH 零写盘、GET 响应体零泄露。关闭不了(同根因 liveness≠authz 的三件暴露面):写——同机另一页面修改他人活跃会话的 advisor 配置(PATCH);读——GET 他人活跃会话的全部评审记录正文与 runtime 状态(records 按会话过滤只是展示口径、过滤≠鉴权,runtime.error 还携带模型原文片段);触发——POST review 烧他人会话的评审额度(busy 门只防同一时刻堆叠、不防持续触发,等空闲后再 POST 即可连环消耗)——该残余风险(三面)用户已知情接受,靠当前宿主能力无法关闭 |
| 2 | 「恰好一次」实为「至多一次」 | 幂等键与水位的消耗发生在渲染之前;无可渲染增量的 turn(典型:模型只发工具调用、结果 role=tool 被 user/assistant 白名单滤掉)被键 + 水位双杀(lib/advisor/observer.js 的 renderAndEmit 游标比较处直接 return) |
该 turn 永久不评——事后补上可见内容再重放同一 turn,实测仍 0 次。需要补评走面板「立即评审一次」 |
| 3 | agentic 分支跨重启会对整段历史补评一次(重复计费) | agentic 路径(从不发 turn/end 的会话)不碰 seen(它没有 turn 边界可依,lib/advisor/observer.js 的 handleEvent agentic 分支无持久化调用),幂等只靠内存游标;重启后游标归零 |
每重启一次,下一次人类输入就对整段历史补评一次 |
| 4 | 只评审主会话汇总,子会话内部 step 不可见 | 数据源封闭:只调当前会话 deriveMessages(),无子会话展开路径;子会话产出回父会话是 tool/result(role=tool),被 user/assistant 白名单直接滤掉(契约 6.2) |
父会话评审看到的是父会话 assistant 自己的汇总文本;子会话要评审得单独给子会话开 advisor |
| 5 | 窗口淘汰后的二次评审边界 | 键出 M 窗口(M=SEEN_WINDOW_SIZE=256)后,宿主若把旧 turn 整组重投且 seq 已抬高水位,会作为新键再评审一次 |
M 窗口 + 水位设计的固有边界,非实现缺陷;对侧取舍是宁可漏评不重复计费 |
| 6 | 多实例共享同一 advisorDataDir 不在支持范围 |
存储侧的「临界区全同步」是进程内串行,跨进程不成立 | 多实例部署需各自指定独立 advisorDataDir |
另两条使用面约束(不是边界,是会直接咬人的事实):
- 与 memory-evolve 的 advisor 语义重叠(它也是只读快照自动评审)。两套不同时开——同回合会被评两次、token 翻倍、右侧两个面板撞车。
- 触发上限不投递、不降级:触顶(
max-tokens)或终态不可信时一律不投递,记runtime.status='error'并落一条记录,绝不降级成 info/recorded——被截断的评审意见基于不完整判断,危险的 blocker 比没有更危险。
4.1 V3 能力面(B1–B5 已实现,2026-10)
- agentic 检索(S1a/S3):普通聊天零检索零子进程(AC-62 把门)——只有代码相关输入才做仓库分析:L1 文件树 + git 事实 + 搜索;L2「相关文件 · 符号精读」按
advisorContextMaxFiles(缺省 4,0=关闭)精读源文件(符号面 = web-tree-sitter AST,降级态为正则启发式且显式标注)。agentic 工具循环受advisorMaxToolRounds(缺省 4,0=关闭)约束,与预取面共享同一 40KB 检索段池。只读边界 = 工具白名单 + git 参数白名单 + 最小 env,不是运行时权限层(契约 §10.1)。 - 决策漂移(AC-24/37):评审输入含仓库
docs/DECISIONS.md的决策条目(来源唯一声明,只有context/decisions.js读它);动作违反既有决策可报blocker(须带证据,见下条)。 - 停止五类 + 证据下限(AC-58/63):note 可带
action(stop-direction/no-new-abstraction/no-premature-impl/verify-assumption/reuse-existing);无evidence的 blocker 一律被规则层降为concern(要报 blocker 必须给出证据文件/决策 ID 与confidence ≥ 0.7)。 - 冷却分级(X11):
blocker/concern免冷却直投 steer;nit 冷却窗口内降级 inject;info 只记录。
5. 成本口径与何时不该开
- 单轮输入 ≈8.5K tokens 起步(口径:
lib/advisor/runtime.js的ADVISOR_MAX_TOKENS常量附近成本量级注释「单轮 input≈8.5K + output 封顶 ≈16K ≈ 25K tokens」;随对话变长与配置advisorMaxMessages变化,这是量级不是精确值)。 - 输出预算
ADVISOR_MAX_TOKENS = 16384,抬高预算不对冲输入窗口(advisorMaxMessages保持 60),首轮最坏 ≈25K tokens——用户知情接受。 - 成本随 turn 数先线性涨、到预算后封顶:评审员是持续会话,跨回合累积,每次评审重放有界历史(字符预算
ADVISOR_CONVERSATION_MAX_CHARS,超预算丢最旧——2026-10-06 P1-3 修复;此前无截断累积会让长会话撞模型上下文上限后永久 error 停摆)+ 本轮增量。 - 据此的开关判据:不需要「每轮都要有人把关」的轻量任务不要开——每轮一次模型调用就是一份起步成本,而这类任务主会话自己就做得完。需要把关的场合(大改造、多轮长跑、方向容易跑偏的活)才值得。
6. 出问题时的排查顺序
按此顺序查,先盘事实再改配置:
- 面板里「来源」chip 是什么?显示「未指定(该会话不评审)」→ 根本是第 3.1 条,先选模型保存。
- 「运行」状态:
error看面板上的「运行异常」文案(未指定模型会在这里明说);disabled→ 该会话没勾启用。 - 是不是开了但一条记录都没有?对照第 4 节边界 2:那一轮可能本来就无可评审增量(模型只调工具)。用「立即评审一次」验证链路通不通。
- 启动日志里有没有废弃键告警?有就说明有人在按旧方式配
cordis*那三个键——它们改了不生效,回到面板重配(不是去改cordis.patch.yml)。 - 有没有「检测到旧全局配置
config.json」告警?有 → 旧配置已停用,面板重配即可。 - 是不是与 memory-evolve 的 advisor 同时开了?两套不同时开(见第 4 节)。
- 以上都对仍异常 → 才考虑代码/环境层,此时再读
docs/advisor-contract.md全文(契约第 0/1/2/4/6/7/8 节是行为的单一事实源)。
7. 自检(收工前回看)
- 说的是 advisor 的行为,而不是 sub agent 的行为(本技能不派活,它只解释一个被动评审机制)?
- 引用行为前核过
docs/advisor-contract.md或lib/advisor/**,而不是凭印象复述? - 讲成本时带了口径(≈、量级、来自哪条记录)?
- 需要「每轮把关」的场合才建议开,而不是无脑推荐?
- 有没有把第 4 节的边界藏起来?尤其边界 1(liveness check ≠ 授权)与边界 3(agentic 重复计费)必须说。