JianFeeeee
a44fd6949b
L2 核心改动：sessions 表补 permission_mode / permission_enforcement 两列 （sqlite + pg 同步），三桥 lib/permission-mode.js 翻译档位到平台原生配置， homeagent advisory 模式提示词告知模型实际强制力。四桥全部携带 from_session_id 供 relay 去重与会话回溯。 FromHuman / ToHuman 判据已加入心跳 payload 与 notify/mail.go。
275 lines
11 KiB
JavaScript
275 lines
11 KiB
JavaScript
/**
|
||
* 权限档位 → 平台原生配置的翻译 —— 四个平台共用的判据。
|
||
*
|
||
* ## 分工
|
||
*
|
||
* **AgentMail 声明，平台执行，插件只翻译。** 这个模块是「翻译」那一步的
|
||
* 唯一实现：把 `plan` / `workspace` / `full` 翻成各平台原生的沙箱/审批配置。
|
||
*
|
||
* 为什么不让插件自己按工具名猜着拦：那会同时违反 I-1（平台原生信号是唯一
|
||
* 真相来源）与 I-4（插件只搬运不决策），而且四个插件对「workspace 到底管
|
||
* 什么」必然各猜一套 —— 同一封 workspace 档的邮件在 A 平台被拦、在 B 平台放行。
|
||
*
|
||
* ## 为什么必须「向更严取整」
|
||
*
|
||
* 平台表达不出精确档位时，一律往更严的方向走，并如实上报自己做到了什么
|
||
* （native / advisory）。pi 就是例子：write/edit 能查 `input.path` 判断越界，
|
||
* 而 bash 命令要碰哪些文件是解析不出来的 —— 于是 workspace 档下 pi 只能
|
||
* 「每条 bash 都问人」，比声明的更严。
|
||
*
|
||
* 不定这条规则的后果：不同插件会朝不同方向取整，而往宽松取整是静默失效
|
||
* （人以为收紧了，实际没有）。
|
||
*/
|
||
|
||
/** 只读：查资料、读代码、出方案，一个字都不许写。 */
|
||
export const MODE_PLAN = 'plan';
|
||
/** 本目录内可动手，越界要问人。默认档。 */
|
||
export const MODE_WORKSPACE = 'workspace';
|
||
/** 自动放行，不问人。 */
|
||
export const MODE_FULL = 'full';
|
||
|
||
/** 全部合法档位，按宽松程度递增。顺序是 modeAtMost 的依据。 */
|
||
export const MODES = [MODE_PLAN, MODE_WORKSPACE, MODE_FULL];
|
||
|
||
/** 没有显式指定时的档位。与 Gateway 的 DefaultPermissionMode 必须一致。 */
|
||
export const DEFAULT_MODE = MODE_WORKSPACE;
|
||
|
||
/** 平台有原生拦截点，档位被真正执行。 */
|
||
export const ENFORCE_NATIVE = 'native';
|
||
/** 平台没有拦截点，档位只写进提示词。 */
|
||
export const ENFORCE_ADVISORY = 'advisory';
|
||
|
||
/**
|
||
* 把外部输入收敛成合法档位。
|
||
*
|
||
* 非法值 → 默认档（**不是** full）。拼错一个档位名不该换来更大的权限。
|
||
* 与 Gateway 的 NormalizePermissionMode 同语义。
|
||
*
|
||
* @param {unknown} mode
|
||
* @returns {string}
|
||
*/
|
||
export function normalizeMode(mode) {
|
||
return MODES.includes(mode) ? mode : DEFAULT_MODE;
|
||
}
|
||
|
||
/**
|
||
* 收敛强制力取值。空串或非法值 → advisory。
|
||
*
|
||
* 保守方向是 advisory 而不是 native：不能替一个没自报过的平台宣称
|
||
* 「档位在这里是被强制的」。
|
||
*
|
||
* @param {unknown} e
|
||
* @returns {string}
|
||
*/
|
||
export function normalizeEnforcement(e) {
|
||
return e === ENFORCE_NATIVE || e === ENFORCE_ADVISORY ? e : ENFORCE_ADVISORY;
|
||
}
|
||
|
||
/**
|
||
* 取两个档位里更严的那一个。
|
||
*
|
||
* 先归一化再比较 —— 两个脏值都变成默认档，于是结果与参数顺序无关（可交换）。
|
||
* Gateway 侧的 ModeAtMost 曾因为「modeRank 把未知值当最严、Normalize 把它
|
||
* 归到默认档」而不可交换，单元测试当场抓到。两边保持同一套语义。
|
||
*
|
||
* @param {string} a
|
||
* @param {string} b
|
||
* @returns {string}
|
||
*/
|
||
export function modeAtMost(a, b) {
|
||
const na = normalizeMode(a);
|
||
const nb = normalizeMode(b);
|
||
return MODES.indexOf(na) <= MODES.indexOf(nb) ? na : nb;
|
||
}
|
||
|
||
/**
|
||
* 这一档会不会产生权限邮件（即需不需要人来点头）。
|
||
*
|
||
* 只有 workspace 档需要人：plan 档当场拒绝、full 档自动放行，两者都不问人。
|
||
* 插件据此决定要不要把平台的权限钩子接到 `/permission/request`。
|
||
*
|
||
* @param {string} mode
|
||
* @returns {boolean}
|
||
*/
|
||
export function modeNeedsHuman(mode) {
|
||
return normalizeMode(mode) === MODE_WORKSPACE;
|
||
}
|
||
|
||
/**
|
||
* opencode 的 permission 规则数组。
|
||
*
|
||
* ## 六条实测结论（不实测就会做出「看起来对但管不住」的东西）
|
||
*
|
||
* 1. **规则是 findLast 胜出**（二进制里
|
||
* `findLast((z)=>g.match(j,z.permission)&&g.match(J,z.pattern))`）
|
||
* → deny 必须放前面、allow 放后面。反了的话连允许的路径也被拒。
|
||
* 2. **pattern 匹配 worktree 相对路径**（`patterns:[relative(y.worktree,file)]`）
|
||
* → 写 `/tmp/**` 这种绝对 pattern 永远匹配不上（`/tmp/x` 相对
|
||
* `/home/program/agentmail` 是 `../../../tmp/x`）。所以 workspace 档用 `**`。
|
||
* 3. **write / edit / patch 共用 `edit` 一个权限名**
|
||
* （`if(A==="write"||A==="edit"||A==="patch"){G.edit=I}`）。
|
||
* 4. **全 deny 让工具从模型清单里消失**（模型自述「I don't have a bash tool
|
||
* available in this session」），部分 deny 则工具保留、越界调用才报错。
|
||
* plan 档用前者更好：模型不会浪费轮次去试。
|
||
* 5. **task（子代理）能绕过父会话权限** —— 实测中模型发现自己没 write，
|
||
* 主动 task 委派给一个带 write 的子代理去写成了。plan/workspace 必须
|
||
* `task deny *`，否则档位形同虚设。
|
||
* 6. **bash 能绕过 edit 的路径限制** —— 模型用 shell 重定向写成了本该被
|
||
* deny 的文件。所以 workspace 档必须同时管 bash，只管 edit 没用。
|
||
*
|
||
* 另注：opencode 原生有 `plan_enter` / `plan_exit` 权限项，与我们的 plan 档
|
||
* **撞名但语义不同**（那是它自己的计划模式开关），这里不碰它们。
|
||
*
|
||
* @param {string} mode
|
||
* @returns {{permission: string, action: string, pattern: string}[]}
|
||
*/
|
||
export function opencodePermissions(mode) {
|
||
const m = normalizeMode(mode);
|
||
|
||
if (m === MODE_FULL) {
|
||
// 全权：不下发任何规则，用平台自己的默认配置。
|
||
// 显式全 allow 会覆盖掉用户在 opencode.jsonc 里的个人设置。
|
||
return [];
|
||
}
|
||
|
||
if (m === MODE_PLAN) {
|
||
// 只读。四项都要 deny：
|
||
// - edit 覆盖 write/edit/patch
|
||
// - bash 否则 shell 重定向就能写文件（实测过）
|
||
// - task 否则子代理能绕过（实测过）
|
||
// - webfetch/websearch 不禁：查资料是 plan 档的本职
|
||
return [
|
||
{ permission: 'edit', action: 'deny', pattern: '*' },
|
||
{ permission: 'bash', action: 'deny', pattern: '*' },
|
||
{ permission: 'task', action: 'deny', pattern: '*' },
|
||
];
|
||
}
|
||
|
||
// workspace：目录内可写，越界问人。
|
||
//
|
||
// deny 在前、allow 在后（findLast 胜出）。pattern `**` 是 worktree
|
||
// 相对路径，等价于「这个工作目录内的任何文件」。
|
||
//
|
||
// bash 一律 ask 而不是 allow：命令要碰哪些文件解析不出来，
|
||
// 这就是「向更严取整」——比声明的严，不比它松。
|
||
//
|
||
// task 仍然 deny：子代理带着自己的权限跑，父会话的边界对它无效。
|
||
return [
|
||
{ permission: 'edit', action: 'deny', pattern: '*' },
|
||
{ permission: 'edit', action: 'allow', pattern: '**' },
|
||
{ permission: 'bash', action: 'ask', pattern: '*' },
|
||
{ permission: 'task', action: 'deny', pattern: '*' },
|
||
];
|
||
}
|
||
|
||
/**
|
||
* DSH 的沙箱模式。
|
||
*
|
||
* 三档与 DSH 原生的三档**一一对应** —— 这不是巧合，是同一个问题的同一个答案
|
||
* （见 `@deepseek-ai/dsh-sandbox-policy` 的 SANDBOX_MODES）。
|
||
*
|
||
* @param {string} mode
|
||
* @returns {'read-only'|'workspace-write'|'danger-full-access'}
|
||
*/
|
||
export function dshSandboxMode(mode) {
|
||
switch (normalizeMode(mode)) {
|
||
case MODE_PLAN: return 'read-only';
|
||
case MODE_FULL: return 'danger-full-access';
|
||
default: return 'workspace-write';
|
||
}
|
||
}
|
||
|
||
/**
|
||
* DSH 的审批策略。
|
||
*
|
||
* 关键实测：`danger-full-access` 对应 `approval: "never"`，而
|
||
* `ApprovalService.decide()` 里 `if (effectivePolicy === "never") return "rejected"`
|
||
* **在 waterfall 之前短路** —— 于是 `approval/request` 钩子根本不触发。
|
||
*
|
||
* 这解释了一个此前查不清的现象：本机 dsh 配了 `defaultPreset: danger-full-access`，
|
||
* 所以整个权限转邮件链路从来没在 dsh 上跑起来过。
|
||
*
|
||
* @param {string} mode
|
||
* @returns {'ask'|'never'}
|
||
*/
|
||
export function dshApprovalPolicy(mode) {
|
||
return modeNeedsHuman(mode) ? 'ask' : 'never';
|
||
}
|
||
|
||
/**
|
||
* pi 侧应当守卫的工具名。
|
||
*
|
||
* pi 只有 `tool_call` 钩子能 `{block:true}`，没有沙箱 —— 所以档位靠
|
||
* 「拦哪些工具」表达：
|
||
*
|
||
* - plan 拦 bash/write/edit（读类工具 read/grep/find/ls 不拦）
|
||
* - workspace 拦同样三个，但 write/edit 可以查 `input.path` 判越界，
|
||
* bash 无法判断 → 一律问人（向更严取整）
|
||
* - full 不拦
|
||
*
|
||
* @param {string} mode
|
||
* @returns {string[]}
|
||
*/
|
||
export function piGuardedTools(mode) {
|
||
return normalizeMode(mode) === MODE_FULL ? [] : ['bash', 'write', 'edit'];
|
||
}
|
||
|
||
/**
|
||
* pi 在某档位下，某次工具调用该不该直接拒绝（不问人）。
|
||
*
|
||
* plan 档下所有被守卫的工具都直接拒绝 —— 该档语义就是「这轮不动手」，
|
||
* 没什么可问人的，模型该把方案写在回信里。
|
||
*
|
||
* workspace 档返回 false（走问人流程）。full 档不会进到这里。
|
||
*
|
||
* @param {string} mode
|
||
* @returns {boolean}
|
||
*/
|
||
export function piBlocksOutright(mode) {
|
||
return normalizeMode(mode) === MODE_PLAN;
|
||
}
|
||
|
||
/**
|
||
* 给模型看的档位说明，放进提示词。
|
||
*
|
||
* 为什么 advisory 时措辞完全不同：那种平台（homeagent）没有任何机制阻止
|
||
* 模型动手，所以只能把约束说成「请你遵守」而不是「你做不到」。
|
||
* 假装它是强制的更危险 —— 模型会以为越界会被拦，于是不必自己小心。
|
||
*
|
||
* @param {{mode: string, enforcement: string, workspace?: string}} ctx
|
||
* @returns {string}
|
||
*/
|
||
export function modeBriefing({ mode, enforcement, workspace }) {
|
||
const m = normalizeMode(mode);
|
||
const enforced = normalizeEnforcement(enforcement) === ENFORCE_NATIVE;
|
||
const dir = workspace ? `\`${workspace}\`` : '本任务的工作目录';
|
||
|
||
if (m === MODE_FULL) {
|
||
return '本任务权限档位：full（全权）。工具调用不需要额外授权。';
|
||
}
|
||
|
||
if (m === MODE_PLAN) {
|
||
return enforced
|
||
? [
|
||
'本任务权限档位：plan（只读）。',
|
||
'写文件、改文件、执行命令都会被平台拦下 —— 这一档只用来查与想。',
|
||
'请把结论、方案、需要人工执行的步骤写在回信里。需要动手请让发件人把档位改成 workspace。',
|
||
].join('\n')
|
||
: [
|
||
'本任务权限档位：plan（只读）。',
|
||
'**这个平台无法强制这一档**，所以约束靠你自己遵守：请不要写文件、改文件或执行命令。',
|
||
'请把结论、方案、需要人工执行的步骤写在回信里。需要动手请让发件人把档位改成 workspace。',
|
||
].join('\n');
|
||
}
|
||
|
||
return enforced
|
||
? [
|
||
`本任务权限档位：workspace。可以在 ${dir} 内读写，越出该目录的写入与命令执行会先向人类请求授权。`,
|
||
'授权可能需要等待，也可能被拒绝 —— 被拒绝时请换一条不需要越界的做法，或在回信里说明需要人工执行哪一步。',
|
||
].join('\n')
|
||
: [
|
||
`本任务权限档位：workspace。请把改动限制在 ${dir} 内。`,
|
||
'**这个平台无法强制这一档**，所以边界靠你自己遵守：需要改该目录之外的东西时，不要直接动手，先在回信里说明。',
|
||
].join('\n');
|
||
}
|