diff --git a/cmd/cyrene/wire_runtime.go b/cmd/cyrene/wire_runtime.go
index 3d1469a..3f605b9 100644
--- a/cmd/cyrene/wire_runtime.go
+++ b/cmd/cyrene/wire_runtime.go
@@ -7,6 +7,8 @@ import (
"path/filepath"
"strings"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/restrict"
"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
@@ -115,9 +117,11 @@ func (a *app) wireMemory(ctx context.Context) error {
return nil
}
-// wireRuntime builds the model adapter, tool dispatcher, guardrails, the agent
-// and its loop, tracing, persistence and the orchestration scheduler.
+// wireRuntime 构建模型适配器、工具 dispatcher、护栏、agent 与其 loop、
+// 追踪、持久化与编排 scheduler。
func (a *app) wireRuntime() error {
+ a.attachToolPolicyStore()
+
// The LLM provider stack is hot-swappable: it loads models.json (or falls
// back to .env) and the panel save endpoint reloads it without a restart
// (design/04 §3.1). a.modelAdapter stays an Adapter (the runtime stack
@@ -213,6 +217,13 @@ func (a *app) wireRuntime() error {
// budget instead.
thinking, reasoningEffort, thinkingShow := a.defaultThinkingOptions()
+ // 敏感操作代审(design/11 §4;裁决 13.4.3):terminal 这类敏感工具在 loop 的
+ // 工具准入门上经主代理代审(复用 orchestration 的 Approver),再由网关把
+ // 结果落进 audit_logs 并广播 design/11 §4 的小字。同一个 Approver 也交给
+ // 编排层(子代理代审),使两条路径共用一处审计。
+ approver := audit.NewApprover(a.log)
+ approvalGate := a.buildApprovalGate(approver)
+
a.loop = loop.New(loop.Options{
Agent: defaultAgent,
Agents: agents,
@@ -239,7 +250,10 @@ func (a *app) wireRuntime() error {
Thinking: thinking,
ReasoningEffort: reasoningEffort,
ThinkingShowToUser: thinkingShow,
- Log: logger.WithSource(a.log, "runtime/loop"),
+ // 按调用(而非整批)准入:敏感与否取决于该次调用的参数
+ // (file 的 read 自主、write 代审),见 toolAdmissionHooks。
+ Hooks: a.toolAdmissionHooks(approvalGate),
+ Log: logger.WithSource(a.log, "runtime/loop"),
})
a.scheduler = orchestration.New(orchestration.Options{
@@ -258,13 +272,108 @@ func (a *app) wireRuntime() error {
// session's live graph, so a branch shows up as a swimlane of that session's
// flow instead of opening a second graph (design/19 §2).
Flow: flowPub,
- Approver: audit.NewApprover(a.log),
+ Approver: approver,
Logger: logger.WithSource(a.log, "orchestration"),
AgentID: defaultAgentID,
})
return nil
}
+// attachToolPolicyStore 接上工具策略的落盘载体(design/11 §3;裁决 1.3/10.4.2)。
+//
+// 它必须在任何工具注册**之前**调用:registry 接到 store 时会立刻 Load 落盘
+// 策略并套到已注册能力上,之后 Register 进来的能力(MCP 热装、插件刷新)也会
+// 拿到落盘值——「重启后策略仍在」正是靠这两条路径合起来成立。
+//
+// 失败只记 WARN 并保留默认值:默认(两个布尔 false = owner-only)就是最严的
+// 一侧,读不出一份策略绝不放宽策略,也不因为策略存储不可用而拖垮启动
+// (写路径仍会诚实报错,不会假装保存成功)。
+func (a *app) attachToolPolicyStore() {
+ log := logger.WithSource(a.log, "cmd/cyrene")
+ store, err := registry.NewSQLitePolicyStore(a.db, a.log)
+ if err != nil {
+ log.Warn("tool policy store unavailable, keeping owner-only defaults", "error", err)
+ return
+ }
+ if err := a.caps.AttachPolicyStore(context.Background(), store); err != nil {
+ log.Warn("tool policy load failed, keeping owner-only defaults", "error", err)
+ }
+}
+
+// buildApprovalGate 构建敏感操作代审门(design/11 §4;裁决 13.4.3)。
+//
+// 归属解析取 Run 上下文里的会话 id 与该 turn 的角色名,使前端小字既投到
+// 正确的会话、也写明是谁想动手(design/11 §4 的「xxx(角色名)」)。会话 id 用
+// loop.FlowOwnerFromContext:子代理的敏感调用归属到**派生它的那个会话**
+// (与 design/19 §2 的 flow 归属同一口径),所以小字出现在主人正在看的对话里,
+// 而不是一个没人查看的子代理 id 下。
+func (a *app) buildApprovalGate(approver *audit.Approver) *restrict.Gate {
+ return restrict.NewGate(
+ auditReviewer{approver: approver},
+ func(ctx context.Context) (string, string) {
+ return loop.FlowOwnerFromContext(ctx), a.approvalActor(ctx)
+ },
+ restrict.WithGateLogger(a.log),
+ )
+}
+
+// toolAdmissionHooks 构建 loop 的工具准入钩子(design/11 §4;裁决 13.4.3):
+// 敏感调用先经主代理代审,代审记录交给网关落 audit_logs 并广播前端小字;
+// 未获代审的调用以软结果回灌给模型(绝不执行)。非敏感调用直接放行。
+//
+// 只装 CallAdmit:敏感与否取决于**该次调用的参数**(file 的 read 自主、
+// write 代审),批量钩子(BatchAdmit)看不到参数,做不出这个区分。
+// 组合根按 loop 的既有契约装配,因此这条链也覆盖子代理的敏感调用
+// (编排层派生的 loop 共享同一组钩子)。
+func (a *app) toolAdmissionHooks(gate *restrict.Gate) loop.ToolLoopHooks {
+ return loop.ToolLoopHooks{
+ CallAdmit: func(ctx context.Context, call agent.ToolCall) *loop.ToolCallVeto {
+ decision := gate.Admit(ctx, call.Name, call.Args)
+ if decision.Approval != nil {
+ // a.gw 在 wireFrontend 才建好;RecordApproval 对 nil 接收者安全。
+ a.gw.RecordApproval(ctx, *decision.Approval)
+ }
+ if !decision.Allow {
+ return &loop.ToolCallVeto{Block: true, Reason: decision.Reason}
+ }
+ return nil
+ },
+ }
+}
+
+// auditReviewer 把 orchestration/audit 的 Approver 适配成代审门的 Reviewer
+// (design/11 §4;裁决 13.4.3 要求复用该 Approver,而不是另起一套代审)。
+// 它只把 Approval 收敛成 (allowed, error),前端小字文案仍由
+// restrict 复用 audit.Approval.Explain 的固定句式产出。
+type auditReviewer struct{ approver *audit.Approver }
+
+// ReviewAndApprove 执行一次代审;approver 缺席时复用编排层的 ErrNoApprover
+// (门据此 fail-closed 拦截敏感操作,绝不静默放行)。
+func (r auditReviewer) ReviewAndApprove(ctx context.Context, actor, action, describe string) (bool, error) {
+ if r.approver == nil {
+ return false, fmt.Errorf("review-and-approve: %w", orchestration.ErrNoApprover)
+ }
+ ap, err := r.approver.ReviewAndApprove(ctx, actor, action, describe)
+ if err != nil {
+ return false, fmt.Errorf("review-and-approve: %w", err)
+ }
+ return ap.Allowed, nil
+}
+
+// approvalActor 解析代审小字里的「谁想动手」:该 turn 绑定的角色名,
+// 未绑定时回落到默认角色;角色名解析不出来就用角色 id(小字宁可用 id
+// 也要说清是谁,但绝不编造一个名字)。
+func (a *app) approvalActor(ctx context.Context) string {
+ pid := loop.SessionEnvFrom(ctx).PersonaID
+ if pid == "" {
+ pid = a.defaultPersonaID()
+ }
+ if name := a.personaName(pid); name != "" {
+ return name
+ }
+ return pid
+}
+
// buildCapacity constructs the awakened-capacity decider when enabled, or nil
// (which keeps the loop's default all-tools behavior). It is opt-in via
// CAPACITY_ENABLED; the allowed-set mapping comes from CAPACITY_TOOL_SETS and
diff --git a/frontend/web/src/components/status.tsx b/frontend/web/src/components/status.tsx
index 9cdbd67..fbec7e2 100644
--- a/frontend/web/src/components/status.tsx
+++ b/frontend/web/src/components/status.tsx
@@ -123,3 +123,27 @@ export function SessionStatusHint(): React.ReactNode | null {
);
}
+
+/** 主代理代审小字(design/11 §4;approval_notice 帧,裁决 13.4.3):敏感操作
+ * (如 terminal 执行命令)经主代理代审后,在聊天流里显示一行小字
+ * 「xxx 想要干什么,我审查后批准了」;被拦截时同一处显示「我审查后拒绝了」。
+ * 文案由后端产出(前端不自己拼),`detail` 作为副文本展示「想干什么」。
+ * 纯展示、无副作用;未收到代审事件时不渲染。 */
+export function ApprovalNoticeHint(): React.ReactNode | null {
+ const notice = useAppStore((s) => s.approvalNotice);
+ if (!notice) return null;
+
+ return (
+
+
+ {notice.explain}
+ {notice.detail ? (
+ {notice.detail}
+ ) : null}
+
+ );
+}
diff --git a/frontend/web/src/lib/types/ws.ts b/frontend/web/src/lib/types/ws.ts
index 1de4fd7..99c6fdb 100644
--- a/frontend/web/src/lib/types/ws.ts
+++ b/frontend/web/src/lib/types/ws.ts
@@ -23,6 +23,34 @@ export interface SessionStatePayload {
pendingCount?: number;
}
+/** approval_notice 下行事件 payload(design/11 §4 主代理代审,裁决 13.4.3):
+ * 敏感操作经代审后的记录。`explain` 是后端产出的固定文案
+ * 「xxx 想要干什么,我审查后批准了 / 拒绝了」,前端原样渲染成小字;
+ * `detail` 是动作摘要(如 "terminal echo hi"),可作副文本。`allowed`
+ * 为 false 表示该敏感调用被拦截(未执行)。这条帧属内容帧,只发给
+ * owner/admin 连接(design/11 §7.1 帧门),viewer 收不到。 */
+export interface ApprovalNoticePayload {
+ actor?: string;
+ tool?: string;
+ op?: string;
+ detail?: string;
+ explain?: string;
+ allowed?: boolean;
+ at?: string;
+}
+
+/** 已归一化的代审记录(store 与组件用):`explain` 必定非空(后端给不出
+ * 文案时前端不渲染,也不编造一句)。 */
+export interface ApprovalNotice {
+ explain: string;
+ actor: string;
+ tool: string;
+ op: string;
+ detail: string;
+ allowed: boolean;
+ at: string;
+}
+
/**
* Downstream WS frame (server → client). `data` is intentionally `unknown`;
* every consumer narrows it. The backend emits `{type, data, turnId?, seq?,
@@ -31,7 +59,8 @@ export interface SessionStatePayload {
* (design/04 §1.1), plus the legacy stream_chunk / stream_end / thinking / mood /
* tool_used / subagent_event / graph_update / reminder / device_update / auth /
* error / task_output, and the capacity/session events from design/14 §5 + 15 §5:
- * capacity_awaken (状态切换+点亮工具), session_busy / session_pending (她是否在忙+挂起消息数).
+ * capacity_awaken (状态切换+点亮工具), session_busy / session_pending (她是否在忙+挂起消息数),
+ * plus approval_notice (design/11 §4 主代理代审小字).
*
* `sessionId` (design/16 §4.2) scopes the frame to one conversation. The hub
* broadcasts globally — every connection of the owner sees every session — so the
diff --git a/frontend/web/src/lib/ws.ts b/frontend/web/src/lib/ws.ts
index 791a866..081d22f 100644
--- a/frontend/web/src/lib/ws.ts
+++ b/frontend/web/src/lib/ws.ts
@@ -10,6 +10,7 @@ import { handleMessageEvent } from "./ws/handlers/message";
import { handleAgentEvent } from "./ws/handlers/agent";
import { handleSessionEvent } from "./ws/handlers/session";
import { handleDeviceEvent } from "./ws/handlers/device";
+import { handleApprovalEvent } from "./ws/handlers/approval";
/**
* Realtime client for `/ws/chat`. Reconnects with exponential backoff and
@@ -49,6 +50,7 @@ export function dispatchFrame(ev: { type: string; sessionId?: string; data: unkn
if (handleAgentEvent(ev, r, s)) return;
if (handleSessionEvent(ev, r, s)) return;
if (handleDeviceEvent(ev, r, s)) return;
+ if (handleApprovalEvent(ev, r, s)) return;
// Unknown future event: keep it in the context log so no frame is lost.
const text = typeof ev.data === "string" ? ev.data : JSON.stringify(ev.data);
diff --git a/frontend/web/src/lib/ws/handlers/approval.test.ts b/frontend/web/src/lib/ws/handlers/approval.test.ts
new file mode 100644
index 0000000..15d78c2
--- /dev/null
+++ b/frontend/web/src/lib/ws/handlers/approval.test.ts
@@ -0,0 +1,88 @@
+// 代审小字的逻辑测试(design/11 §4;approval_notice 帧,裁决 13.4.3)。
+// 项目没有前端测试框架/jsdom,所以这是一个零依赖的纯 node 检查:它驱动真实的
+// 帧解码器(lib/ws.ts 的 dispatchFrame)与真实的 store,断言
+// ApprovalNoticeHint 组件所读的那几个字段,并在第一个失败处抛出。
+//
+// 跑法(用 vite 自带的 esbuild,不新增依赖、不改 package.json;banner 补上
+// store 的 persist 中间件在 node 下探测的 window.localStorage):
+//
+// cd frontend/web \
+// && ./node_modules/.bin/esbuild src/lib/ws/handlers/approval.test.ts \
+// --bundle --platform=node --format=esm \
+// --banner:js='globalThis.window={localStorage:{getItem:()=>null,setItem:()=>{},removeItem:()=>{}}};' \
+// --outfile=/tmp/cyrene-approval.test.mjs \
+// && node /tmp/cyrene-approval.test.mjs
+//
+// `tsc --noEmit`(npm run build 的一部分)会对本文件做类型检查,因此它
+// 只从项目内导入、不 import node:*。
+
+import { dispatchFrame } from "../../ws";
+import { useAppStore } from "../../../store/useAppStore";
+
+let checks = 0;
+
+function ok(cond: boolean, what: string): void {
+ checks += 1;
+ if (!cond) throw new Error(`FAILED: ${what}`);
+}
+
+function same(got: T, want: T, what: string): void {
+ ok(JSON.stringify(got) === JSON.stringify(want), `${what} — got ${JSON.stringify(got)}, want ${JSON.stringify(want)}`);
+}
+
+const store = useAppStore.getState();
+
+// 激活会话 + 一条代审帧(后端 RecordApproval 广播的形状)。
+store.setActiveSession("web");
+store.setApprovalNotice(null);
+
+dispatchFrame({
+ type: "approval_notice",
+ sessionId: "web",
+ data: {
+ actor: "昔涟",
+ tool: "terminal",
+ op: "执行命令",
+ detail: "terminal echo hi",
+ explain: "「昔涟 想要干什么,我审查后批准了」",
+ allowed: true,
+ at: "2026-10-04T12:00:00Z",
+ },
+});
+
+const notice = useAppStore.getState().approvalNotice;
+ok(notice !== null, "approval_notice 帧应写入 approvalNotice(组件据此渲染小字)");
+same(notice?.explain, "「昔涟 想要干什么,我审查后批准了」", "小字文案原样来自后端 explain");
+same(notice?.detail, "terminal echo hi", "动作摘要作为副文本");
+same(notice?.allowed, true, "批准态");
+same(notice?.tool, "terminal", "工具名");
+
+// 别的会话发生的代审不写进当前会话的小字(与流式帧同一作用域规则)。
+store.setApprovalNotice(null);
+dispatchFrame({
+ type: "approval_notice",
+ sessionId: "web:other",
+ data: { explain: "「别的角色 想要干什么,我审查后批准了」" },
+});
+ok(useAppStore.getState().approvalNotice === null, "别的会话的代审不得写进当前会话");
+
+// 没有文案的帧被丢掉(前端不自己拼文案)。
+store.setActiveSession("web");
+dispatchFrame({ type: "approval_notice", sessionId: "web", data: { tool: "terminal" } });
+ok(useAppStore.getState().approvalNotice === null, "没有 explain 的帧应被丢弃");
+
+// 拒绝态:小字保留「拒绝了」的文案,组件按 allowed=false 换色/换图标。
+dispatchFrame({
+ type: "approval_notice",
+ sessionId: "web",
+ data: { explain: "「昔涟 想要干什么,我审查后拒绝了」", allowed: false, detail: "terminal rm -rf /" },
+});
+const denied = useAppStore.getState().approvalNotice;
+same(denied?.allowed, false, "拒绝态");
+same(denied?.explain, "「昔涟 想要干什么,我审查后拒绝了」", "拒绝小字");
+
+// 会话切换后重置(resetChat 清掉小字,避免上一段对话的代审留在新会话里)。
+useAppStore.getState().resetChat();
+ok(useAppStore.getState().approvalNotice === null, "resetChat 应清掉代审小字");
+
+console.log(`approval notice: ${checks} checks passed`);
diff --git a/frontend/web/src/lib/ws/handlers/approval.ts b/frontend/web/src/lib/ws/handlers/approval.ts
new file mode 100644
index 0000000..e6b3618
--- /dev/null
+++ b/frontend/web/src/lib/ws/handlers/approval.ts
@@ -0,0 +1,27 @@
+import { streamFrameApplies } from "../../streamScope";
+import type { FrameEvent, FramePayload, StoreState } from "./shared";
+
+/** 代审帧处理组:approval_notice —— 主代理代审小字(design/11 §4,裁决 13.4.3)。
+ * 敏感操作(如 terminal)经代审后后端广播该帧,`explain` 是后端产出的固定文案
+ * 「xxx 想要干什么,我审查后批准了 / 拒绝了」,前端原样渲染成聊天流里的一行小字。
+ * 命中返回 true,未命中返回 false 交给下一组。 */
+export function handleApprovalEvent(ev: FrameEvent, r: FramePayload, s: StoreState): boolean {
+ if (ev.type !== "approval_notice") return false;
+ // 与流式帧同一作用域规则:别的会话发生的代审不写进当前会话的小字。
+ if (!streamFrameApplies(ev, r, s.activeSessionId)) return true;
+ // 没有文案就没有可渲染的小字 —— 丢掉这帧,而不是编造一句。
+ const explain = typeof r?.explain === "string" ? r.explain : "";
+ if (!explain) return true;
+ s.setApprovalNotice({
+ explain,
+ actor: typeof r?.actor === "string" ? r.actor : "",
+ tool: typeof r?.tool === "string" ? r.tool : "",
+ op: typeof r?.op === "string" ? r.op : "",
+ detail: typeof r?.detail === "string" ? r.detail : "",
+ // 后端只在整条代审失败/拒绝时发 allowed=false;缺字段按「已批准」处理,
+ // 与后端 RecordApproval 写入的布尔一致。
+ allowed: r?.allowed !== false,
+ at: typeof r?.at === "string" ? r.at : "",
+ });
+ return true;
+}
diff --git a/frontend/web/src/modes/ChatShell.tsx b/frontend/web/src/modes/ChatShell.tsx
index d48e427..f0048cf 100644
--- a/frontend/web/src/modes/ChatShell.tsx
+++ b/frontend/web/src/modes/ChatShell.tsx
@@ -8,7 +8,7 @@ import { HistoryList } from "../components/messages/HistoryList";
import { ChatInput } from "../components/ChatInput";
import { EmptyState } from "../components/primitives";
import { Icon } from "../components/Icon";
-import { SessionStatusHint } from "../components/status";
+import { SessionStatusHint, ApprovalNoticeHint } from "../components/status";
import { personaChatBackground, type Orientation } from "../lib/persona";
/**
@@ -76,6 +76,7 @@ export function ChatShell(): React.ReactNode {
+
{messages.length === 0 ? (
}
diff --git a/frontend/web/src/store/useAppStore.ts b/frontend/web/src/store/useAppStore.ts
index 908e775..2989ae9 100644
--- a/frontend/web/src/store/useAppStore.ts
+++ b/frontend/web/src/store/useAppStore.ts
@@ -3,6 +3,7 @@ import { persist } from "zustand/middleware";
import type {
AdminChannelMessage,
AgentInfo,
+ ApprovalNotice,
AwakenState,
BackthinkItem,
ChatMessage,
@@ -51,6 +52,10 @@ export interface AppStore {
/** 会话编排(design/15 §5)——她是否在忙 + 挂起消息数(不阻塞输入框)。 */
sessionBusy: boolean;
pendingCount: number;
+ /** 最近一次主代理代审小字(design/11 §4;`approval_notice` 帧,裁决 13.4.3):
+ * 敏感操作经代审后显示一行「xxx 想要干什么,我审查后批准了」。同一时刻只留
+ * 最近一条(新的覆盖旧的),且**不持久化** —— 代审是实时事件,刷新后不重放。 */
+ approvalNotice: ApprovalNotice | null;
/** 适配器消息日志实时事件(`channel_persisted` WS 帧,design/16 §4.6 §4)——
* 隔离会话(群聊/陌生人)落库后秒推,供 IM 适配器日志页增量插入。最新在前,
@@ -124,6 +129,8 @@ export interface AppStore {
tool?: string | null
) => void;
setSessionBusy: (busy: boolean, pendingCount?: number) => void;
+ /** 记录一条主代理代审小字(`approval_notice` WS 帧)。null 表示清除。 */
+ setApprovalNotice: (notice: ApprovalNotice | null) => void;
taskLogs: Record
;
appendTaskLog: (taskId: string, text: string) => void;
@@ -152,6 +159,7 @@ export const useAppStore = create()(
awakenTool: null,
sessionBusy: false,
pendingCount: 0,
+ approvalNotice: null,
personas: [],
taskLogs: {},
channelEvents: [],
@@ -371,6 +379,7 @@ export const useAppStore = create()(
sessionBusy: busy,
pendingCount: pendingCount ?? s.pendingCount,
})),
+ setApprovalNotice: (notice) => set({ approvalNotice: notice }),
appendTaskLog: (taskId, text) =>
set((s) => ({
@@ -404,6 +413,7 @@ export const useAppStore = create()(
awakenTool: null,
sessionBusy: false,
pendingCount: 0,
+ approvalNotice: null,
})),
}),
{
diff --git a/internal/capability/registry/policy_store.go b/internal/capability/registry/policy_store.go
new file mode 100644
index 0000000..4ae92b0
--- /dev/null
+++ b/internal/capability/registry/policy_store.go
@@ -0,0 +1,169 @@
+package registry
+
+import (
+ "context"
+ "database/sql"
+ "fmt"
+ "log/slog"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+)
+
+// PolicyStore 持久化工具级可达性标记(design/11 §3、design/09 §2.1;裁决 1.3/10.4.2)。
+//
+// 载体是 SQLite 的 tool_policies 表(迁移 0012_tool_policy);*SQLitePolicyStore
+// 是生产实现,测试可换成内存桩。实现必须对并发使用安全。
+type PolicyStore interface {
+ // Load 返回全部已落盘的策略,键为能力名。从未配置过的能力不出现在结果里
+ // ——调用方按默认值(两个布尔均 false = owner-only)处理,即 fail-closed。
+ Load(ctx context.Context) (map[string]ToolPolicy, error)
+ // Save 写入一个能力的策略:不存在则插入,存在则更新(并把 updated_at
+ // 推进到当前时间)。name 为空是非法调用,返回错误。
+ Save(ctx context.Context, name string, p ToolPolicy) error
+}
+
+// 策略持久化的 SQL(全参数化,项目规范 §十)。表由迁移 0012_tool_policy 建立;
+// upsert 以唯一索引 idx_tool_policies_name 为冲突目标,因此同一能力永远只有一行。
+const (
+ selectToolPoliciesSQL = `SELECT name, allow_in_group, allow_in_stranger FROM tool_policies`
+ upsertToolPolicySQL = `
+INSERT INTO tool_policies (name, allow_in_group, allow_in_stranger)
+VALUES (?, ?, ?)
+ON CONFLICT(name) DO UPDATE SET
+ allow_in_group = excluded.allow_in_group,
+ allow_in_stranger = excluded.allow_in_stranger,
+ updated_at = strftime('%Y-%m-%dT%H:%M:%fZ','now')`
+)
+
+// AttachPolicyStore 把持久化载体接到注册表(design/11 §3;裁决 1.3/10.4.2):
+//
+// 1. 立即 Load 全部落盘策略,套用到**已注册**的能力上(重启后策略仍在);
+// 2. 记住这份快照与 store,之后 Register 进来的能力(MCP 热装、插件刷新)
+// 会用落盘值覆盖其初始标记;
+// 3. 此后 SetPolicy/SetAllowInGroup/SetAllowInStranger 先落库、成功后才改内存。
+//
+// store 为 nil 是合法的空操作(注册表保持纯内存,即既有行为)。Load 失败时
+// 返回错误且不动任何内存状态——调用方可以选择忽略(默认值就是最严的
+// owner-only,fail-closed),但绝不能把「没有读出策略」当成「策略全开」。
+func (r *Registry) AttachPolicyStore(ctx context.Context, store PolicyStore) error {
+ if r == nil || store == nil {
+ return nil
+ }
+ loaded, err := store.Load(ctx)
+ if err != nil {
+ return fmt.Errorf("registry: attach policy store: %w", err)
+ }
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ r.store = store
+ r.persisted = loaded
+ for name, pol := range loaded {
+ cap, ok := r.caps[name]
+ if !ok {
+ continue // 能力尚未注册:Register 时会用 r.persisted 套上
+ }
+ cap.Policy = pol
+ r.caps[name] = cap
+ }
+ return nil
+}
+
+// persist 把一条策略写进已装上的 store(未装时空操作)。它刻意在注册表锁之外
+// 执行 SQL,调用方只在它成功后才改内存——即「先落库、后改内存」。
+//
+// 它用 context.Background():策略写入口是管理端点经 CapabilityStore 窄接口
+// (gateway/contracts.go)调用的既有签名 SetPolicy(name, p),没有 ctx 可传;
+// 本地 SQLite 单行 upsert 是短操作,不值得为此改契约。
+func (r *Registry) persist(name string, p ToolPolicy) error {
+ store := r.storeSnapshot()
+ if store == nil {
+ return nil
+ }
+ if err := store.Save(context.Background(), name, p); err != nil {
+ return fmt.Errorf("registry: persist policy %q: %w", name, err)
+ }
+ return nil
+}
+
+// storeSnapshot 在锁内读一次 store 指针,避免与 AttachPolicyStore 的写入竞态。
+func (r *Registry) storeSnapshot() PolicyStore {
+ r.mu.RLock()
+ defer r.mu.RUnlock()
+ return r.store
+}
+
+// remember 记录刚落盘成功的策略(调用方必须已持有写锁)。它使「卸下再重注册」
+// 的能力(插件刷新)仍拿到最新标记,而不是注册时的零值。
+func (r *Registry) remember(name string, p ToolPolicy) {
+ if r.store == nil {
+ return
+ }
+ if r.persisted == nil {
+ r.persisted = make(map[string]ToolPolicy)
+ }
+ r.persisted[name] = p
+}
+
+// SQLitePolicyStore 把工具策略持久化在 SQLite 的 tool_policies 表上。
+// 它凭借底层的 *sql.DB 对并发使用安全。
+type SQLitePolicyStore struct {
+ db *sql.DB
+ log *slog.Logger
+}
+
+// NewSQLitePolicyStore 在 db 上构建 SQLite 策略存储。db 为 nil 时返回错误。
+//
+// 它刻意不自建 DDL:迁移 0012_tool_policy 是这份 schema 的唯一权威路径,
+// 因此表缺失时 Load/Save 会返回明确的错误(调用方据此保持最严默认值),
+// 而不是悄悄降级成内存态、让管理面板的「保存成功」变成重启即复位的假成功。
+func NewSQLitePolicyStore(db *sql.DB, log *slog.Logger) (*SQLitePolicyStore, error) {
+ if db == nil {
+ return nil, fmt.Errorf("registry: policy store: nil database")
+ }
+ return &SQLitePolicyStore{db: db, log: logger.WithSource(log, "capability/registry")}, nil
+}
+
+// Load 返回 tool_policies 的全部行。空表返回空 map(不是错误):那就是
+// 「从未配置过任何标记」的诚实状态,所有能力按默认 owner-only 处理。
+func (s *SQLitePolicyStore) Load(ctx context.Context) (map[string]ToolPolicy, error) {
+ if s == nil || s.db == nil {
+ return nil, fmt.Errorf("registry: policy store: not configured")
+ }
+ rows, err := s.db.QueryContext(ctx, selectToolPoliciesSQL)
+ if err != nil {
+ return nil, fmt.Errorf("registry: load tool policies: %w", err)
+ }
+ defer rows.Close()
+
+ out := make(map[string]ToolPolicy)
+ for rows.Next() {
+ var (
+ name string
+ allowInGroup bool
+ allowInStranger bool
+ )
+ if err := rows.Scan(&name, &allowInGroup, &allowInStranger); err != nil {
+ return nil, fmt.Errorf("registry: scan tool policy: %w", err)
+ }
+ out[name] = ToolPolicy{AllowInGroup: allowInGroup, AllowInStranger: allowInStranger}
+ }
+ if err := rows.Err(); err != nil {
+ return nil, fmt.Errorf("registry: iterate tool policies: %w", err)
+ }
+ return out, nil
+}
+
+// Save upsert name 的策略。两条布尔标记本身不是敏感信息(能力名 + 两个布尔),
+// 因此错误信息只带能力名;日志也不打印任何参数外的内容。
+func (s *SQLitePolicyStore) Save(ctx context.Context, name string, p ToolPolicy) error {
+ if s == nil || s.db == nil {
+ return fmt.Errorf("registry: policy store: not configured")
+ }
+ if name == "" {
+ return fmt.Errorf("registry: save tool policy: %w", ErrInvalidArgument)
+ }
+ if _, err := s.db.ExecContext(ctx, upsertToolPolicySQL, name, p.AllowInGroup, p.AllowInStranger); err != nil {
+ return fmt.Errorf("registry: save tool policy %q: %w", name, err)
+ }
+ return nil
+}
diff --git a/internal/capability/registry/policy_store_test.go b/internal/capability/registry/policy_store_test.go
new file mode 100644
index 0000000..0f073dc
--- /dev/null
+++ b/internal/capability/registry/policy_store_test.go
@@ -0,0 +1,293 @@
+package registry
+
+import (
+ "context"
+ "database/sql"
+ "errors"
+ "io"
+ "log/slog"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/db"
+)
+
+// 本文件锁定裁决 1.3/10.4.2(工具策略落盘):迁移 0012_tool_policy 的 up/down
+// 可逆、以及「重启后策略仍在」——后者用「关连接、重建注册表、再 Load」模拟
+// 一次真实重启。
+
+// errStoreDown 是内存桩注入的落盘失败。
+var errStoreDown = errors.New("policy store down")
+
+// testStoreLogger 返回一个静默 logger:存储层测试不关心日志输出。
+func testStoreLogger() *slog.Logger {
+ return slog.New(slog.NewTextHandler(io.Discard, nil))
+}
+
+// openMigrated 开一个(文件或 :memory:)库并跑完全部迁移。
+// 用文件而非 :memory: 的用例是因为「重启仍在」要跨连接读同一份数据。
+func openMigrated(t *testing.T, path string) *sql.DB {
+ t.Helper()
+ ctx := context.Background()
+ conn, err := db.Open(ctx, path, testStoreLogger())
+ if err != nil {
+ t.Fatalf("db.Open(%s): %v", path, err)
+ }
+ if err := db.MigrateUp(ctx, conn, testStoreLogger()); err != nil {
+ conn.Close()
+ t.Fatalf("MigrateUp: %v", err)
+ }
+ t.Cleanup(func() { conn.Close() })
+ return conn
+}
+
+// toolPoliciesTableExists 报告 tool_policies 表是否存在。
+func toolPoliciesTableExists(t *testing.T, ctx context.Context, conn *sql.DB) bool {
+ t.Helper()
+ var name string
+ err := conn.QueryRowContext(ctx,
+ `SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'tool_policies'`).Scan(&name)
+ if errors.Is(err, sql.ErrNoRows) {
+ return false
+ }
+ if err != nil {
+ t.Fatalf("query sqlite_master: %v", err)
+ }
+ return true
+}
+
+// copyFile 复制一个文件(副本迁移验证用)。
+func copyFile(t *testing.T, src, dst string) {
+ t.Helper()
+ data, err := os.ReadFile(src)
+ if err != nil {
+ t.Fatalf("read %s: %v", src, err)
+ }
+ if err := os.WriteFile(dst, data, 0o600); err != nil {
+ t.Fatalf("write %s: %v", dst, err)
+ }
+}
+
+// TestToolPolicyMigration_UpDownUpOnDataDirCopy 在 data/cyrene.db 的**副本**上
+// 跑迁移 0012 的 up → down → up,证明可逆且幂等(绝不碰本体)。
+// 副本不存在时跳过(例如干净检出的 CI),此时 :memory: 的用例仍然覆盖同一迁移。
+func TestToolPolicyMigration_UpDownUpOnDataDirCopy(t *testing.T) {
+ ctx := context.Background()
+ src := filepath.Join("..", "..", "..", "data", "cyrene.db")
+ if _, err := os.Stat(src); err != nil {
+ t.Skipf("data/cyrene.db 不可读,跳过副本迁移验证: %v", err)
+ }
+ dst := filepath.Join(t.TempDir(), "cyrene-copy.db")
+ copyFile(t, src, dst)
+ // WAL 模式下已提交内容可能还在 -wal 里,一并带过去,副本才是完整快照。
+ for _, suffix := range []string{"-wal", "-shm"} {
+ if _, err := os.Stat(src + suffix); err == nil {
+ copyFile(t, src+suffix, dst+suffix)
+ }
+ }
+
+ conn, err := db.Open(ctx, dst, testStoreLogger())
+ if err != nil {
+ t.Fatalf("db.Open(copy): %v", err)
+ }
+ defer conn.Close()
+
+ if err := db.MigrateUp(ctx, conn, testStoreLogger()); err != nil {
+ t.Fatalf("MigrateUp(copy): %v", err)
+ }
+ if !toolPoliciesTableExists(t, ctx, conn) {
+ t.Fatal("tool_policies 应在 MigrateUp 后存在")
+ }
+ if _, err := conn.ExecContext(ctx,
+ `INSERT INTO tool_policies (name, allow_in_group) VALUES ('copied_tool', 1)`); err != nil {
+ t.Fatalf("insert into copy: %v", err)
+ }
+
+ // down:只回滚最后一步(= 0012)。
+ if err := db.MigrateDown(ctx, conn, 1, testStoreLogger()); err != nil {
+ t.Fatalf("MigrateDown(copy, 1): %v", err)
+ }
+ if toolPoliciesTableExists(t, ctx, conn) {
+ t.Fatal("tool_policies 应在 MigrateDown 后消失")
+ }
+
+ // 再 up:可逆且幂等。
+ if err := db.MigrateUp(ctx, conn, testStoreLogger()); err != nil {
+ t.Fatalf("MigrateUp(copy, 2nd): %v", err)
+ }
+ if !toolPoliciesTableExists(t, ctx, conn) {
+ t.Fatal("tool_policies 应在第二次 MigrateUp 后重新出现")
+ }
+ var rows int
+ if err := conn.QueryRowContext(ctx, `SELECT COUNT(*) FROM tool_policies`).Scan(&rows); err != nil {
+ t.Fatalf("count rows: %v", err)
+ }
+ if rows != 0 {
+ t.Fatalf("回滚再升级后应有 0 行,得到 %d 行(回滚未清空?)", rows)
+ }
+}
+
+// TestToolPolicyMigration_UpDownOnMemory 在干净库上锁定同一迁移的 up/down
+// (不依赖 data/ 目录是否存在)。
+func TestToolPolicyMigration_UpDownOnMemory(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ conn := openMigrated(t, ":memory:")
+
+ if !toolPoliciesTableExists(t, ctx, conn) {
+ t.Fatal("tool_policies 应在 MigrateUp 后存在")
+ }
+ if err := db.MigrateDown(ctx, conn, 1, testStoreLogger()); err != nil {
+ t.Fatalf("MigrateDown: %v", err)
+ }
+ if toolPoliciesTableExists(t, ctx, conn) {
+ t.Fatal("tool_policies 应在 MigrateDown 后消失")
+ }
+}
+
+// TestRegistry_PolicyStoreSurvivesRestart 锁定「重启后策略仍在」:
+// 第一次运行 Save,第二次运行(新连接 + 新注册表 + 新 store)Load 回来。
+func TestRegistry_PolicyStoreSurvivesRestart(t *testing.T) {
+ ctx := context.Background()
+ path := filepath.Join(t.TempDir(), "cyrene.db")
+
+ first := openMigrated(t, path)
+ store, err := NewSQLitePolicyStore(first, testStoreLogger())
+ if err != nil {
+ t.Fatalf("NewSQLitePolicyStore: %v", err)
+ }
+ reg := New()
+ if err := reg.AttachPolicyStore(ctx, store); err != nil {
+ t.Fatalf("AttachPolicyStore: %v", err)
+ }
+ for _, name := range []string{"group_tool", "other"} {
+ if err := reg.RegisterTool(regTool{name: name}); err != nil {
+ t.Fatalf("RegisterTool(%s): %v", name, err)
+ }
+ }
+ // 初始值必须是默认(两个布尔 false = owner-only)。
+ if pol, err := reg.Policy("group_tool"); err != nil || pol.AllowInGroup || pol.AllowInStranger {
+ t.Fatalf("initial policy = %+v (err %v), want both false", pol, err)
+ }
+ if err := reg.SetPolicy("group_tool", ToolPolicy{AllowInGroup: true}); err != nil {
+ t.Fatalf("SetPolicy: %v", err)
+ }
+ if err := first.Close(); err != nil { // 模拟进程退出
+ t.Fatalf("close first connection: %v", err)
+ }
+
+ second := openMigrated(t, path)
+ store2, err := NewSQLitePolicyStore(second, testStoreLogger())
+ if err != nil {
+ t.Fatalf("NewSQLitePolicyStore(2): %v", err)
+ }
+ reg2 := New()
+ if err := reg2.AttachPolicyStore(ctx, store2); err != nil {
+ t.Fatalf("AttachPolicyStore(2): %v", err)
+ }
+ // 重启后注册表里还没有能力,只有 Load 出的策略快照……
+ if _, err := reg2.Policy("group_tool"); !errors.Is(err, ErrNotFound) {
+ t.Fatalf("Policy before re-register error = %v, want ErrNotFound", err)
+ }
+ // ……能力注册进来的那一刻套上落盘值(MCP 热装等晚注册路径同理)。
+ if err := reg2.RegisterTool(regTool{name: "group_tool"}); err != nil {
+ t.Fatalf("RegisterTool(2): %v", err)
+ }
+ pol, err := reg2.Policy("group_tool")
+ if err != nil {
+ t.Fatalf("Policy(2): %v", err)
+ }
+ if !pol.AllowInGroup || pol.AllowInStranger {
+ t.Fatalf("policy after restart = %+v, want {AllowInGroup:true AllowInStranger:false}", pol)
+ }
+ // 没配过的能力仍是默认(tool_policies 里没有它的行)。
+ if err := reg2.RegisterTool(regTool{name: "other"}); err != nil {
+ t.Fatalf("RegisterTool(other): %v", err)
+ }
+ if pol, err := reg2.Policy("other"); err != nil || pol.AllowInGroup || pol.AllowInStranger {
+ t.Fatalf("unconfigured policy = %+v (err %v), want both false", pol, err)
+ }
+}
+
+// TestRegistry_AttachPolicyStoreAppliesToRegisteredCaps 锁定反向顺序:
+// 能力先注册、策略后 Load(AttachPolicyStore 在 wireRuntime 才启用的场景),
+// 已注册能力也必须立刻拿到落盘值。
+func TestRegistry_AttachPolicyStoreAppliesToRegisteredCaps(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ seed := newMemoryPolicyStore()
+ seed.marks["stranger_tool"] = ToolPolicy{AllowInStranger: true}
+
+ reg := New()
+ if err := reg.RegisterTool(regTool{name: "stranger_tool"}); err != nil {
+ t.Fatalf("RegisterTool: %v", err)
+ }
+ if err := reg.AttachPolicyStore(ctx, seed); err != nil {
+ t.Fatalf("AttachPolicyStore: %v", err)
+ }
+ pol, err := reg.Policy("stranger_tool")
+ if err != nil {
+ t.Fatalf("Policy: %v", err)
+ }
+ if pol.AllowInGroup || !pol.AllowInStranger {
+ t.Fatalf("policy after attach = %+v, want {AllowInGroup:false AllowInStranger:true}", pol)
+ }
+}
+
+// TestRegistry_SetPolicyPersistFailureKeepsMemory 锁定「先落库、后改内存」:
+// 落盘失败时内存保持旧值且返回错误,绝不出现「面板说成功、重启却复位」。
+func TestRegistry_SetPolicyPersistFailureKeepsMemory(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ store := newMemoryPolicyStore()
+ reg := New()
+ if err := reg.RegisterTool(regTool{name: "calc"}); err != nil {
+ t.Fatalf("RegisterTool: %v", err)
+ }
+ if err := reg.AttachPolicyStore(ctx, store); err != nil {
+ t.Fatalf("AttachPolicyStore: %v", err)
+ }
+ store.failSave = true
+ if err := reg.SetPolicy("calc", ToolPolicy{AllowInGroup: true}); err == nil {
+ t.Fatal("SetPolicy with failing store = nil error, want error")
+ }
+ pol, err := reg.Policy("calc")
+ if err != nil {
+ t.Fatalf("Policy: %v", err)
+ }
+ if pol.AllowInGroup || pol.AllowInStranger {
+ t.Fatalf("policy after failed persist = %+v, want unchanged (both false)", pol)
+ }
+ // 单布尔入口(SetAllowInGroup/SetAllowInStranger)走同一条落库路径。
+ if err := reg.SetAllowInGroup("calc", true); err == nil {
+ t.Fatal("SetAllowInGroup with failing store = nil error, want error")
+ }
+}
+
+// memoryPolicyStore 是 PolicyStore 的内存桩:Load/Save 语义与 SQLite 实现一致
+// (只保存写过的能力),failSave 用于注入落盘失败。
+type memoryPolicyStore struct {
+ marks map[string]ToolPolicy
+ failSave bool
+}
+
+func newMemoryPolicyStore() *memoryPolicyStore {
+ return &memoryPolicyStore{marks: make(map[string]ToolPolicy)}
+}
+
+func (m *memoryPolicyStore) Load(_ context.Context) (map[string]ToolPolicy, error) {
+ out := make(map[string]ToolPolicy, len(m.marks))
+ for k, v := range m.marks {
+ out[k] = v
+ }
+ return out, nil
+}
+
+func (m *memoryPolicyStore) Save(_ context.Context, name string, p ToolPolicy) error {
+ if m.failSave {
+ return errStoreDown
+ }
+ m.marks[name] = p
+ return nil
+}
diff --git a/internal/capability/registry/registry.go b/internal/capability/registry/registry.go
index 12d9f99..da3c36d 100644
--- a/internal/capability/registry/registry.go
+++ b/internal/capability/registry/registry.go
@@ -68,6 +68,14 @@ type Capability struct {
type Registry struct {
mu sync.RWMutex
caps map[string]Capability
+ // store 是策略落盘载体(design/11 §3、裁决 10.4.2)。为 nil 时注册表
+ // 退回纯内存态(既有行为);AttachPolicyStore 装上后,SetPolicy 系列
+ // 先落库再改内存。
+ store PolicyStore
+ // persisted 是最近一次落盘成功的策略快照(能力名 → 标记)。注册表在
+ // Register 时用它覆盖能力的初始 Policy,因此「策略在能力注册之前就已落盘」
+ // 与「能力先注册、策略后落盘」两种顺序都得到同一个结果。
+ persisted map[string]ToolPolicy
}
// Compile-time assertion that *Registry satisfies the SDK Registrar interface.
@@ -102,6 +110,11 @@ func (r *Registry) Register(cap Capability) error {
if _, exists := r.caps[cap.Name]; exists {
return fmt.Errorf("registry: register %q: %w", cap.Name, ErrDuplicate)
}
+ // 落盘策略覆盖注册时带的初始标记:DB 是策略的权威载体(裁决 10.4.2),
+ // 因此重启后先 Load、再热注册(MCP 热装等)也能拿到已配置的值。
+ if pol, ok := r.persisted[cap.Name]; ok {
+ cap.Policy = pol
+ }
r.caps[cap.Name] = cap
return nil
}
@@ -160,7 +173,17 @@ func (r *Registry) Policy(name string) (ToolPolicy, error) {
// SetPolicy replaces the reachability markers for the capability named name. It
// returns ErrNotFound when no such capability is registered.
+//
+// 落盘(裁决 1.3/10.4.2):已装上 PolicyStore 时先写库,成功后才改内存——
+// 写库失败即返回错误、内存保持旧值,绝不产生「面板说保存成功、重启却复位」。
+// 顺序是「存在性读 → 落库(锁外做 SQL)→ 持锁套用」。
func (r *Registry) SetPolicy(name string, p ToolPolicy) error {
+ if _, err := r.Policy(name); err != nil {
+ return fmt.Errorf("registry: set policy %q: %w", name, err)
+ }
+ if err := r.persist(name, p); err != nil {
+ return err
+ }
r.mu.Lock()
defer r.mu.Unlock()
cap, ok := r.caps[name]
@@ -169,34 +192,35 @@ func (r *Registry) SetPolicy(name string, p ToolPolicy) error {
}
cap.Policy = p
r.caps[name] = cap
+ r.remember(name, p)
return nil
}
// SetAllowInGroup toggles the group-chat marker for the capability named name.
-// It returns ErrNotFound when no such capability is registered.
+// It returns ErrNotFound when no such capability is registered. 它复用
+// setPolicyField,因此同样先落库再改内存(裁决 10.4.2)。
func (r *Registry) SetAllowInGroup(name string, allow bool) error {
- r.mu.Lock()
- defer r.mu.Unlock()
- cap, ok := r.caps[name]
- if !ok {
- return fmt.Errorf("registry: set allow_in_group %q: %w", name, ErrNotFound)
- }
- cap.Policy.AllowInGroup = allow
- r.caps[name] = cap
- return nil
+ return r.setPolicyField(name, "allow_in_group", func(p *ToolPolicy) { p.AllowInGroup = allow })
}
// SetAllowInStranger toggles the stranger-chat marker for the capability named
-// name. It returns ErrNotFound when no such capability is registered.
+// name. It returns ErrNotFound when no such capability is registered. 同
+// SetAllowInGroup:先落库再改内存。
func (r *Registry) SetAllowInStranger(name string, allow bool) error {
- r.mu.Lock()
- defer r.mu.Unlock()
- cap, ok := r.caps[name]
- if !ok {
- return fmt.Errorf("registry: set allow_in_stranger %q: %w", name, ErrNotFound)
+ return r.setPolicyField(name, "allow_in_stranger", func(p *ToolPolicy) { p.AllowInStranger = allow })
+}
+
+// setPolicyField 是三个策略写入口共用的「读当前值 → 改一位 → SetPolicy」路径
+// (先落库再改内存,见 SetPolicy)。field 只用于错误消息里的操作名。
+func (r *Registry) setPolicyField(name, field string, apply func(*ToolPolicy)) error {
+ cur, err := r.Policy(name)
+ if err != nil {
+ return fmt.Errorf("registry: set %s %q: %w", field, name, err)
+ }
+ apply(&cur)
+ if err := r.SetPolicy(name, cur); err != nil {
+ return fmt.Errorf("registry: set %s %q: %w", field, name, err)
}
- cap.Policy.AllowInStranger = allow
- r.caps[name] = cap
return nil
}
diff --git a/internal/capability/restrict/approve.go b/internal/capability/restrict/approve.go
new file mode 100644
index 0000000..d6785e9
--- /dev/null
+++ b/internal/capability/restrict/approve.go
@@ -0,0 +1,168 @@
+package restrict
+
+import (
+ "context"
+ "log/slog"
+ "time"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/orchestration/audit"
+)
+
+// 本文件是 design/11 §4「敏感操作代审」的准入侧实现(裁决 13.4.3):
+// loop 的工具钩子(ToolLoopHooks.CallAdmit / BatchAdmit)调用 Gate.Admit,
+// 敏感调用经主代理代审、非敏感调用自主放行。落库与前端小字广播不在本包
+// ——Gate 只产出记录(Decision.Approval),由组合根交给 gateway 落 audit_logs
+// 并广播 approval_notice 帧。
+
+// Reviewer 执行一次主代理代审(design/11 §4)。
+//
+// 生产实现适配 *audit.Approver(组合根注入,见 cmd/cyrene/wire_runtime.go);
+// 用窄接口是为了本包能用桩测试,不必起编排层。
+type Reviewer interface {
+ // ReviewAndApprove 审核归属 actor 的角色想做的 action,返回是否放行。
+ // describe 是给审查者看的动作说明。空白 actor/action/describe 或 ctx 取消
+ // 由实现返回错误;返回错误时门按 fail-closed 拦截。
+ ReviewAndApprove(ctx context.Context, actor, action, describe string) (allowed bool, err error)
+}
+
+// Resolver 从一次 Run 的上下文解析代审归属(design/11 §4 小字里的「xxx」):
+// sessionID = 该 Run 的会话(前端小字的投递目标,可为空表示不定位会话),
+// actor = 想动手的角色名。组合根用 loop.SessionFromContext + 该会话的角色解析。
+type Resolver func(ctx context.Context) (sessionID, actor string)
+
+// ApprovalEvent 是一次代审的完整记录(design/11 §4 §8:who / what / when /
+// result + 前端小字)。组合根把它落进 audit_logs 并广播给前端。
+type ApprovalEvent struct {
+ // SessionID 是该次 Run 的会话 id(可为空)。
+ SessionID string
+ // Actor 是想要动手的角色名(小字里的 xxx)。
+ Actor string
+ // Tool 是敏感工具名(如 terminal)。
+ Tool string
+ // Op 是敏感操作类别(执行命令 / 修改文件 / 网络访问)。
+ Op SensitiveOp
+ // Detail 是动作摘要(工具 + 关键参数,已截断)。
+ Detail string
+ // Explain 是前端小字文案(design/11 §4 的固定句式)。
+ Explain string
+ // Allowed 报告代审是否放行。
+ Allowed bool
+ // At 是代审发生时间。
+ At time.Time
+}
+
+// Decision 是一次工具调用准入的结论。
+type Decision struct {
+ // Allow 报告该调用是否放行。
+ Allow bool
+ // Reason 是拦截时回灌给模型的软提示(放行时为空),体例与既有安全门的
+ // "not_allowed: ..." 一致,使模型能重新评估而不是硬崩。
+ Reason string
+ // Approval 是本次代审的记录;非敏感调用为 nil。调用方负责记录它
+ // (审计落库 + 前端小字),放行与拦截都要记(design/11 §8)。
+ Approval *ApprovalEvent
+}
+
+// Gate 是 loop 的工具准入门(design/11 §4;裁决 13.4.3):敏感操作走主代理
+// 代审,其余自主放行。它对并发使用安全(无可变状态)。
+type Gate struct {
+ reviewer Reviewer
+ resolve Resolver
+ log *slog.Logger
+}
+
+// GateOption 配置一个 Gate。
+type GateOption func(*Gate)
+
+// WithGateLogger 让门把每次代审结论与拦截原因记到 l(来源标
+// capability/restrict)。为 nil 时不记日志。
+func WithGateLogger(l *slog.Logger) GateOption {
+ return func(g *Gate) { g.log = logger.WithSource(l, "capability/restrict") }
+}
+
+// NewGate 构建代审门。reviewer 为 nil 时门是 fail-closed 的:所有敏感调用
+// 一律拦截并留下一条「未获代审」的拒绝记录——绝不因为没有代审者就静默放行。
+// resolve 为 nil 时归属解析为空(actor 为空会让小字退化,但判定不受影响)。
+func NewGate(reviewer Reviewer, resolve Resolver, opts ...GateOption) *Gate {
+ g := &Gate{reviewer: reviewer, resolve: resolve}
+ for _, opt := range opts {
+ opt(g)
+ }
+ return g
+}
+
+// Admit 判定一次工具调用:非敏感立即放行(不产生代审记录),敏感调用先做
+// 主代理代审再决定放行或拦截。返回的 Decision.Approval 非 nil 时必须由调用方
+// 记录(design/11 §8:代审动作批准/拒绝各落一行)。
+func (g *Gate) Admit(ctx context.Context, name string, args map[string]any) Decision {
+ op, detail, sensitive := SensitiveCall(name, args)
+ if !sensitive {
+ return Decision{Allow: true}
+ }
+ sessionID, actor := g.resolveCtx(ctx)
+ action := string(op)
+ if detail != "" {
+ action += ":" + detail
+ }
+ ev := &ApprovalEvent{
+ SessionID: sessionID,
+ Actor: actor,
+ Tool: name,
+ Op: op,
+ Detail: detail,
+ At: time.Now(),
+ }
+ if g == nil || g.reviewer == nil {
+ ev.Explain = approvalExplain(actor, false)
+ g.logf("敏感操作无代审者,按 fail-closed 拦截", name, actor, nil)
+ return Decision{Allow: false, Reason: approvalDeniedReason(name), Approval: ev}
+ }
+ allowed, err := g.reviewer.ReviewAndApprove(ctx, actor, action, detail)
+ if err != nil {
+ ev.Explain = approvalExplain(actor, false)
+ g.logf("代审失败,按 fail-closed 拦截", name, actor, err)
+ return Decision{Allow: false, Reason: approvalDeniedReason(name), Approval: ev}
+ }
+ ev.Allowed = allowed
+ ev.Explain = approvalExplain(actor, allowed)
+ g.logf("敏感操作代审", name, actor, nil)
+ if !allowed {
+ return Decision{Allow: false, Reason: approvalDeniedReason(name), Approval: ev}
+ }
+ return Decision{Allow: true, Approval: ev}
+}
+
+// resolveCtx 解析归属;Resolver 为 nil 时返回两个空串(判定不依赖它们)。
+func (g *Gate) resolveCtx(ctx context.Context) (string, string) {
+ if g == nil || g.resolve == nil {
+ return "", ""
+ }
+ return g.resolve(ctx)
+}
+
+// logf 记一条带来源的代审日志:只记工具名与角色名,**不记动作摘要**
+// (参数里可能有秘密;摘要只进本包的 ApprovalEvent 与审计 who/what/result 链)。
+func (g *Gate) logf(msg, tool, actor string, err error) {
+ if g == nil || g.log == nil {
+ return
+ }
+ args := []any{"tool", tool, "actor", actor}
+ if err != nil {
+ args = append(args, "error", err)
+ }
+ g.log.Info(msg, args...)
+}
+
+// approvalDeniedReason 是敏感操作未获代审放行时回灌给模型的软提示,
+// 与 loop 安全门文案(not_allowed: ...)同一体例。
+func approvalDeniedReason(name string) string {
+ return "not_approved: sensitive tool " + name + " requires the main agent's approval"
+}
+
+// approvalExplain 产出前端小字文案。它复用 orchestration/audit 的固定句式
+// (design/11 §4:「xxx 想要干什么,我审查后批准了」),使代审成功与
+// 「无代审者/代审报错」两条路径的小字完全一致,不出现两份文案。
+func approvalExplain(actor string, allowed bool) string {
+ return audit.Approval{Actor: actor, Allowed: allowed}.Explain()
+}
diff --git a/internal/capability/restrict/approve_test.go b/internal/capability/restrict/approve_test.go
new file mode 100644
index 0000000..5183ac6
--- /dev/null
+++ b/internal/capability/restrict/approve_test.go
@@ -0,0 +1,134 @@
+package restrict
+
+import (
+ "context"
+ "errors"
+ "testing"
+)
+
+// reviewStub 是 Reviewer 的桩:记录调用、按配置返回结论或错误。
+type reviewStub struct {
+ allowed bool
+ err error
+ calls []reviewCall
+}
+
+type reviewCall struct{ actor, action, describe string }
+
+func (s *reviewStub) ReviewAndApprove(_ context.Context, actor, action, describe string) (bool, error) {
+ s.calls = append(s.calls, reviewCall{actor: actor, action: action, describe: describe})
+ if s.err != nil {
+ return false, s.err
+ }
+ return s.allowed, nil
+}
+
+// staticResolver 固定返回一遍归属。
+func staticResolver(sessionID, actor string) Resolver {
+ return func(context.Context) (string, string) { return sessionID, actor }
+}
+
+// TestGate_NonSensitivePassesWithoutApproval 锁定「非敏感自主」:读文件/检索
+// 不进代审、不产生记录。
+func TestGate_NonSensitivePassesWithoutApproval(t *testing.T) {
+ t.Parallel()
+ rv := &reviewStub{allowed: true}
+ g := NewGate(rv, staticResolver("web", "昔涟"))
+ d := g.Admit(context.Background(), "file", map[string]any{"action": "read", "path": "/data/a.md"})
+ if !d.Allow {
+ t.Fatalf("读文件应自主放行,得到 %+v", d)
+ }
+ if d.Approval != nil {
+ t.Fatalf("非敏感调用不应产生代审记录: %+v", d.Approval)
+ }
+ if len(rv.calls) != 0 {
+ t.Fatalf("非敏感调用不应触发代审,代审者被调用 %d 次", len(rv.calls))
+ }
+}
+
+// TestGate_SensitiveToolTriggersApproval 是裁决 13.4.3 的反向用例(loop 侧):
+// terminal 不再自主执行,而是触发主代理代审,并把记录交给调用方落审计。
+func TestGate_SensitiveToolTriggersApproval(t *testing.T) {
+ t.Parallel()
+ rv := &reviewStub{allowed: true}
+ g := NewGate(rv, staticResolver("web", "昔涟"))
+ d := g.Admit(context.Background(), "terminal", map[string]any{"command": "echo hi"})
+ if !d.Allow {
+ t.Fatalf("代审批准后应放行,得到 %+v", d)
+ }
+ if len(rv.calls) != 1 {
+ t.Fatalf("代审者调用次数 = %d, want 1", len(rv.calls))
+ }
+ if rv.calls[0].actor != "昔涟" {
+ t.Fatalf("代审归属 actor = %q, want 昔涟", rv.calls[0].actor)
+ }
+ if rv.calls[0].action != "执行命令:terminal echo hi" {
+ t.Fatalf("代审动作 = %q, want 执行命令:terminal echo hi", rv.calls[0].action)
+ }
+ ev := d.Approval
+ if ev == nil {
+ t.Fatal("敏感调用放行也必须留下代审记录(design/11 §8:批准/拒绝各落一行)")
+ }
+ if !ev.Allowed || ev.SessionID != "web" || ev.Actor != "昔涟" || ev.Tool != "terminal" || ev.Op != SensitiveExecCommand {
+ t.Fatalf("代审记录 = %+v", ev)
+ }
+ if ev.Explain != "「昔涟 想要干什么,我审查后批准了」" {
+ t.Fatalf("前端小字 = %q, want design/11 §4 的固定句式", ev.Explain)
+ }
+ if ev.At.IsZero() {
+ t.Fatal("代审记录应带时间戳")
+ }
+}
+
+// TestGate_DeniedSensitiveCallIsBlocked 锁定拒绝路径:代审不放行 → 调用被拦截、
+// 回灌软提示、记录里 Allowed=false 且小字换成「拒绝了」。
+func TestGate_DeniedSensitiveCallIsBlocked(t *testing.T) {
+ t.Parallel()
+ rv := &reviewStub{allowed: false}
+ g := NewGate(rv, staticResolver("web", "昔涟"))
+ d := g.Admit(context.Background(), "terminal", map[string]any{"command": "rm -rf /"})
+ if d.Allow {
+ t.Fatalf("代审未放行却被放行: %+v", d)
+ }
+ if d.Reason == "" {
+ t.Fatal("拦截必须给出回灌给模型的说明")
+ }
+ if d.Approval == nil || d.Approval.Allowed {
+ t.Fatalf("拒绝也要落记录且 Allowed=false: %+v", d.Approval)
+ }
+ if d.Approval.Explain != "「昔涟 想要干什么,我审查后拒绝了」" {
+ t.Fatalf("拒绝小字 = %q", d.Approval.Explain)
+ }
+}
+
+// TestGate_ReviewerFailureIsFailClosed 锁定 fail-closed:代审者报错(或压根
+// 没配)时敏感操作一律拦截并留下拒绝记录,绝不静默放行。
+func TestGate_ReviewerFailureIsFailClosed(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ for name, g := range map[string]*Gate{
+ "reviewer error": NewGate(&reviewStub{err: errors.New("approver down")}, staticResolver("web", "昔涟")),
+ "no reviewer": NewGate(nil, staticResolver("web", "昔涟")),
+ } {
+ d := g.Admit(ctx, "terminal", map[string]any{"command": "echo hi"})
+ if d.Allow {
+ t.Fatalf("%s: 敏感调用被放行,应 fail-closed 拦截", name)
+ }
+ if d.Approval == nil || d.Approval.Allowed {
+ t.Fatalf("%s: 应留下 Allowed=false 的代审记录: %+v", name, d.Approval)
+ }
+ }
+}
+
+// TestGate_NilGateDeniesSensitive 锁定零值安全:未装配的门(nil 接收者)碰到
+// 敏感调用按拦截处理,而不是 panic 或放行。
+func TestGate_NilGateDeniesSensitive(t *testing.T) {
+ t.Parallel()
+ var g *Gate
+ if d := g.Admit(context.Background(), "terminal", map[string]any{"command": "echo hi"}); d.Allow {
+ t.Fatalf("nil 门应拦截敏感调用: %+v", d)
+ }
+ if d := g.Admit(context.Background(), "calculator", nil); !d.Allow {
+ t.Fatalf("nil 门的非敏感调用仍应放行: %+v", d)
+ }
+}
diff --git a/internal/capability/restrict/sensitive.go b/internal/capability/restrict/sensitive.go
new file mode 100644
index 0000000..8bd0534
--- /dev/null
+++ b/internal/capability/restrict/sensitive.go
@@ -0,0 +1,88 @@
+package restrict
+
+import (
+ "strings"
+ "unicode/utf8"
+)
+
+// SensitiveOp 是 design/11 §4「敏感清单」里的操作类别。它只用于审计与前端
+// 小字(「xxx 想要干什么,我审查后批准了」),不参与身份/权限判定——身份始终
+// 由 channel 层 actor 元数据 + 白名单决定(design/11 §0 红线)。
+type SensitiveOp string
+
+const (
+ // SensitiveExecCommand 执行命令(terminal)。
+ SensitiveExecCommand SensitiveOp = "执行命令"
+ // SensitiveWriteFile 修改文件(file 工具的 write 动作)。
+ SensitiveWriteFile SensitiveOp = "修改文件"
+ // SensitiveNetwork 网络访问。只有会改变外部状态的写方法算敏感:
+ // GET/HEAD/OPTIONS 属「检索」,可自主(design/11 §4)。
+ SensitiveNetwork SensitiveOp = "网络访问"
+)
+
+// sensitiveSummaryRunes 截断动作摘要:代审小字与审计只需一眼看出「想干什么」,
+// 同时限制进入前端/日志的文本块大小(也降低把长参数里的秘密整段搬进日志的机会)。
+const sensitiveSummaryRunes = 80
+
+// SensitiveCall 判定一次工具调用是否属敏感操作(design/11 §4)。
+//
+// 判定完全结构化:只看工具名 + 参数,绝不由模型文本推断(design/11 §0 红线)。
+// 返回操作类别、动作摘要与是否敏感。清单与项目实际的工具面对应如下:
+//
+// terminal → 执行命令(命令原文进摘要)
+// file (action=write) → 修改文件(路径进摘要)
+// http (method=POST) → 网络访问(URL 进摘要)
+//
+// 其余情况一律**不敏感**:file 的 read/list/search、http 的 GET/HEAD/OPTIONS、
+// knowledge / web-search / web-fetch(检索)、calculator / datetime / text /
+// json / markdown / random(纯计算)、vision / ocr / session_read(只读)——
+// 与 design/11 §4「非敏感(读文件 / 检索 / 查记忆)可自主」一致。
+//
+// 未知工具(含 MCP 工具)同样不敏感:工具面已由 registry 的策略闸门管理,
+// 这里不新增「未知即拦截」的硬边界,否则任何新工具都会在主人会话里被拦死。
+func SensitiveCall(name string, args map[string]any) (SensitiveOp, string, bool) {
+ switch name {
+ case "terminal":
+ return SensitiveExecCommand, summarize("terminal", argString(args, "command")), true
+ case "file":
+ if argString(args, "action") != "write" {
+ return "", "", false
+ }
+ return SensitiveWriteFile, summarize("file write", argString(args, "path")), true
+ case "http":
+ method := strings.ToUpper(strings.TrimSpace(argString(args, "method")))
+ if method == "" || method == "GET" || method == "HEAD" || method == "OPTIONS" {
+ return "", "", false
+ }
+ return SensitiveNetwork, summarize("http "+method, argString(args, "url")), true
+ default:
+ return "", "", false
+ }
+}
+
+// summarize 拼接「动作 + 目标」摘要并按 sensitiveSummaryRunes 截断(不切开
+// 多字节字符);目标为空时只返回动作。
+func summarize(action, target string) string {
+ target = strings.TrimSpace(target)
+ if target == "" {
+ return action
+ }
+ return action + " " + clipRunes(target, sensitiveSummaryRunes)
+}
+
+// clipRunes 把 s 截到至多 max 个 rune,超出时追加省略号;max 非正时原样返回。
+func clipRunes(s string, max int) string {
+ if max <= 0 || utf8.RuneCountInString(s) <= max {
+ return s
+ }
+ return string([]rune(s)[:max]) + "…"
+}
+
+// argString 从工具参数里取一个字符串字段;参数表缺失或类型不符返回 ""。
+func argString(args map[string]any, key string) string {
+ if args == nil {
+ return ""
+ }
+ s, _ := args[key].(string)
+ return s
+}
diff --git a/internal/capability/restrict/sensitive_test.go b/internal/capability/restrict/sensitive_test.go
new file mode 100644
index 0000000..9286966
--- /dev/null
+++ b/internal/capability/restrict/sensitive_test.go
@@ -0,0 +1,73 @@
+package restrict
+
+import (
+ "strings"
+ "testing"
+)
+
+// TestSensitiveCall 是 design/11 §4 敏感清单的判定表:执行命令/修改文件/
+// 网络写方法敏感,读文件/检索/纯计算自主。
+func TestSensitiveCall(t *testing.T) {
+ t.Parallel()
+ cases := []struct {
+ name string
+ args map[string]any
+ wantOp SensitiveOp
+ wantIn string // 摘要应包含的片段(wantSensitive 时)
+ sensitive bool
+ }{
+ {name: "terminal", args: map[string]any{"command": "rm -rf /tmp/x"}, wantOp: SensitiveExecCommand, wantIn: "rm -rf /tmp/x", sensitive: true},
+ {name: "terminal", args: nil, wantOp: SensitiveExecCommand, wantIn: "terminal", sensitive: true},
+ {name: "file", args: map[string]any{"action": "write", "path": "/data/a.md"}, wantOp: SensitiveWriteFile, wantIn: "/data/a.md", sensitive: true},
+ {name: "file", args: map[string]any{"action": "read", "path": "/data/a.md"}},
+ {name: "file", args: map[string]any{"action": "list"}},
+ {name: "file", args: map[string]any{"action": "search", "query": "x"}},
+ {name: "http", args: map[string]any{"method": "POST", "url": "https://example.com/hook"}, wantOp: SensitiveNetwork, wantIn: "example.com/hook", sensitive: true},
+ {name: "http", args: map[string]any{"method": "post", "url": "https://example.com/hook"}, wantOp: SensitiveNetwork, sensitive: true},
+ {name: "http", args: map[string]any{"url": "https://example.com"}}, // method 缺省 = GET
+ {name: "http", args: map[string]any{"method": "GET", "url": "https://example.com"}},
+ {name: "http", args: map[string]any{"method": "HEAD"}},
+ {name: "knowledge", args: map[string]any{"query": "设计文档"}},
+ {name: "web-search", args: map[string]any{"query": "x"}},
+ {name: "web-fetch", args: map[string]any{"url": "https://example.com"}},
+ {name: "session_read", args: map[string]any{"sessionId": "web"}},
+ {name: "calculator", args: map[string]any{"expression": "1+1"}},
+ {name: "mcp:some-server/tool", args: map[string]any{"anything": true}},
+ {name: "unknown-tool", args: nil},
+ }
+ for _, tc := range cases {
+ op, detail, sensitive := SensitiveCall(tc.name, tc.args)
+ if sensitive != tc.sensitive {
+ t.Fatalf("SensitiveCall(%s, %v) sensitive = %v, want %v", tc.name, tc.args, sensitive, tc.sensitive)
+ }
+ if !tc.sensitive {
+ if op != "" || detail != "" {
+ t.Fatalf("SensitiveCall(%s) 非敏感时不应给出类别/摘要,得到 (%q, %q)", tc.name, op, detail)
+ }
+ continue
+ }
+ if op != tc.wantOp {
+ t.Fatalf("SensitiveCall(%s) op = %q, want %q", tc.name, op, tc.wantOp)
+ }
+ if tc.wantIn != "" && !strings.Contains(detail, tc.wantIn) {
+ t.Fatalf("SensitiveCall(%s) detail = %q, want it to contain %q", tc.name, detail, tc.wantIn)
+ }
+ }
+}
+
+// TestSensitiveCall_SummaryIsClipped 锁定动作摘要的截断:长参数不许整段
+// 进入小字/审计(同时不切开多字节字符)。
+func TestSensitiveCall_SummaryIsClipped(t *testing.T) {
+ t.Parallel()
+ long := strings.Repeat("昔", 200)
+ _, detail, sensitive := SensitiveCall("terminal", map[string]any{"command": long})
+ if !sensitive {
+ t.Fatal("terminal 应判定为敏感")
+ }
+ if got := len([]rune(detail)); got > sensitiveSummaryRunes+len("terminal ")+1 {
+ t.Fatalf("摘要 rune 数 = %d,未按 %d 截断: %q", got, sensitiveSummaryRunes, detail)
+ }
+ if !strings.HasSuffix(detail, "…") {
+ t.Fatalf("被截断的摘要应以省略号结尾: %q", detail)
+ }
+}
diff --git a/internal/db/migrations/0012_tool_policy.down.sql b/internal/db/migrations/0012_tool_policy.down.sql
new file mode 100644
index 0000000..d84627e
--- /dev/null
+++ b/internal/db/migrations/0012_tool_policy.down.sql
@@ -0,0 +1,9 @@
+-- 0012_tool_policy down: 回滚落盘的工具策略表。
+--
+-- 回滚后的状态是「策略只活在内存、重启复位」(裁决 1.3/10.4.2 落地前的旧形态):
+-- 已配置的标记随表一起丢弃,重启后所有能力回到默认的两布尔 false(owner-only)。
+-- 丢弃是安全的——registry 的运行时内存副本与调用路径不读本表以外的东西,
+-- 且不存在引用它的外键(内部按能力名匹配,非外键约束)。
+DROP INDEX IF EXISTS idx_tool_policies_name;
+
+DROP TABLE IF EXISTS tool_policies;
diff --git a/internal/db/migrations/0012_tool_policy.up.sql b/internal/db/migrations/0012_tool_policy.up.sql
new file mode 100644
index 0000000..dc0243a
--- /dev/null
+++ b/internal/db/migrations/0012_tool_policy.up.sql
@@ -0,0 +1,27 @@
+-- 0012_tool_policy: 工具级可达性标记落盘(design/11 §3、design/09 §2.1;裁决 1.3/10.4.2)。
+--
+-- 每个能力(工具/技能/MCP 等)两个独立布尔 allow_in_group / allow_in_stranger,
+-- 默认 0 = 仅主人(owner-only);群聊与陌生人环境只有标记为真的能力可被调用
+-- (策略引擎读值见 internal/capability/restrict)。
+--
+-- 为什么必须落盘:裁决 1.3「时 per-tool 为准且必须落盘」——此前标记只活在
+-- capability registry 的内存里,管理面板 POST /api/v1/admin/plugins/policy
+-- 改完一重启就复位。本表是那份策略的权威载体(registry 启动时 Load,
+-- SetPolicy 时先落库再改内存,见 internal/capability/registry/policy_store.go)。
+--
+-- 口径:一行 = 一个已配置过的能力名;没有行的能力按默认值(两布尔均 0)
+-- 处理,因此本表不需要为每个内置工具预填行——默认即最严(fail-closed)。
+-- name 是能力名(工具名 / "mcp:" 等),唯一索引承载「一个能力一行」。
+-- 表名用复数,援引 AGENTS §10 已登记的例外(既有迁移口径一致)。
+CREATE TABLE IF NOT EXISTS tool_policies (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ name TEXT NOT NULL,
+ allow_in_group INTEGER NOT NULL DEFAULT 0,
+ allow_in_stranger INTEGER NOT NULL DEFAULT 0,
+ created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')),
+ updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
+);
+
+-- 唯一索引同时承担 upsert 的冲突目标(ON CONFLICT(name) 需要唯一约束/索引)。
+CREATE UNIQUE INDEX IF NOT EXISTS idx_tool_policies_name
+ ON tool_policies (name);
diff --git a/internal/services/gateway/admin_approval.go b/internal/services/gateway/admin_approval.go
new file mode 100644
index 0000000..46af19f
--- /dev/null
+++ b/internal/services/gateway/admin_approval.go
@@ -0,0 +1,70 @@
+package gateway
+
+import (
+ "context"
+ "time"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/restrict"
+)
+
+// 本文件是 design/11 §4「敏感操作代审」的对外侧实现(裁决 13.4.3):
+// loop 的工具准入钩子判定出「该敏感操作已获(或未获)代审」后,组合根
+// 把记录交给这里——① 落审计链 audit_logs(who/what/when/result),
+// ② 向 owner/admin 连接广播小字帧。判定与代审本身在
+// internal/capability/restrict(Gate);本文件只管「记录 + 呈现」。
+
+// wsApprovalNotice 是主代理代审小字的 WS 事件类型(design/11 §4)。
+// 它携带内容(角色名、动作、文案),因此 design/11 §7.1 的帧门默认
+// fail-closed:只投递给 owner + admin 连接,viewer 收不到,也不进那 7 个
+// 状态机信号白名单。
+const wsApprovalNotice = "approval_notice"
+
+// 代审在审计链里的 who/what/result 口径(design/11 §8):
+// who = 想动手的角色名,what = "approval.<工具名>",result = granted|denied。
+// 代审动作批准/拒绝**各落一行**,因此前缀固定、结果二分。
+const (
+ approvalAuditPrefix = "approval."
+ approvalResultGrant = "granted"
+ approvalResultDeny = "denied"
+)
+
+// RecordApproval 记录一次主代理代审(design/11 §4 §8;裁决 13.4.3)。
+//
+// ① 审计:把 who(角色名)/ what(approval.<工具名>)/ when / result
+// (granted / denied)追加进 audit_logs —— 代审动作批准与拒绝各落一行,
+// 供管理面板「可观测性 → 审计」与通知 feed 查询。
+// ② 前端小字:广播 approval_notice 帧,携带 design/11 §4 的固定文案
+// 「xxx(角色名) 想要干什么,我审查后批准了」(explain),以及工具名、
+// 操作类别与动作摘要(detail,客户端可作副文本或忽略)。
+//
+// 审计写入用 context.WithoutCancel:代审发生在一次 Run 内部,而 Run 的 ctx
+// 可能已被取消(用户中断)——已经发生的代审仍然必须留痕。审计存储坏掉时
+// gateway.audit 只记一条日志,不影响代审已经成立的结论。
+//
+// 方法对 nil 接收者安全(组合根在网关构建完成前调用它时不会 panic)。
+func (s *Server) RecordApproval(ctx context.Context, ev restrict.ApprovalEvent) {
+ if s == nil {
+ return
+ }
+ if ctx == nil {
+ ctx = context.Background()
+ }
+ result := approvalResultDeny
+ if ev.Allowed {
+ result = approvalResultGrant
+ }
+ s.audit(context.WithoutCancel(ctx), ev.Actor, approvalAuditPrefix+ev.Tool, result)
+ s.hub.broadcast(wsEvent{
+ Type: wsApprovalNotice,
+ SessionID: ev.SessionID,
+ Data: map[string]any{
+ "actor": ev.Actor,
+ "tool": ev.Tool,
+ "op": string(ev.Op),
+ "detail": ev.Detail,
+ "explain": ev.Explain,
+ "allowed": ev.Allowed,
+ "at": ev.At.UTC().Format(time.RFC3339Nano),
+ },
+ })
+}
diff --git a/internal/services/gateway/admin_approval_test.go b/internal/services/gateway/admin_approval_test.go
new file mode 100644
index 0000000..5ba03ef
--- /dev/null
+++ b/internal/services/gateway/admin_approval_test.go
@@ -0,0 +1,230 @@
+package gateway
+
+import (
+ "context"
+ "database/sql"
+ "encoding/json"
+ "io"
+ "log/slog"
+ "path/filepath"
+ "testing"
+ "time"
+
+ "github.com/gorilla/websocket"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/restrict"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/db"
+)
+
+// 本文件锁定裁决 13.4.3 的对外侧:敏感操作经代审后**落 audit_logs**
+// (who/what/when/result)并向 owner/admin 广播 design/11 §4 的小字帧
+// `approval_notice`。判定/代审本身由 internal/capability/restrict 的 Gate
+// 钉住(restrict/approve_test.go),这里钉住「记录 + 呈现」,以及
+// design/11 §7.1 的帧门(viewer 收不到这条内容帧)。
+
+// approvalReviewer 是 restrict.Reviewer 的桩:记录调用并固定批准。
+type approvalReviewer struct {
+ calls int
+ allowed bool
+}
+
+func (r *approvalReviewer) ReviewAndApprove(context.Context, string, string, string) (bool, error) {
+ r.calls++
+ return r.allowed, nil
+}
+
+// newApprovalEnv 接线一个带**真实 SQLite 审计存储**的网关 —— 用例要断言
+// audit_logs 里真的有行,因此不能用内存回退存储。
+func newApprovalEnv(t *testing.T) (*Server, string, *auth.JWTService, *sql.DB) {
+ t.Helper()
+ ctx := context.Background()
+ conn, err := db.Open(ctx, filepath.Join(t.TempDir(), "cyrene.db"), slog.New(slog.NewTextHandler(io.Discard, nil)))
+ if err != nil {
+ t.Fatalf("open sqlite: %v", err)
+ }
+ t.Cleanup(func() { conn.Close() })
+ auditStore, err := NewSQLiteAuditStore(ctx, conn, nil)
+ if err != nil {
+ t.Fatalf("audit store: %v", err)
+ }
+ srv, ts, jwt := buildEnv(t, nil, Deps{AuditStore: auditStore})
+ return srv, ts.URL, jwt, conn
+}
+
+// ownerWSConn 建立一条 owner 连接,并用一次 mode_switch 往返确认它已注册
+// 到 hub(与既有的 flow_update/role-gate 用例同法)。
+func ownerWSConn(t *testing.T, url, token string) *websocket.Conn {
+ t.Helper()
+ conn := dialWS(t, url, token)
+ t.Cleanup(func() { conn.Close() })
+ if err := conn.WriteJSON(wsInbound{Type: "mode_switch", Data: json.RawMessage(`{"mode":"chat"}`)}); err != nil {
+ t.Fatalf("write mode_switch: %v", err)
+ }
+ if typ, raw := readWire(t, conn, "mode_switch ack"); typ != "mode_switch" {
+ t.Fatalf("first frame = %q, want mode_switch (%s)", typ, raw)
+ }
+ return conn
+}
+
+// TestRecordApproval_TerminalTriggersApprovalAndLandsInAuditLogs 是裁决 13.4.3
+// 的反向用例(gateway 侧):terminal 这类敏感调用**走代审**——判定敏感 →
+// 代审放行 → audit_logs 落一行 → 前端收到小字帧。此前 terminal 直接执行、
+// 审计链里没有「代审」痕迹,本用例就是把那条链钉死。
+func TestRecordApproval_TerminalTriggersApprovalAndLandsInAuditLogs(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ srv, url, jwt, conn := newApprovalEnv(t)
+ wsConn := ownerWSConn(t, url, signAny(t, jwt, "acct", auth.RoleOwner))
+
+ args := map[string]any{"command": "echo hi"}
+ if _, _, sensitive := restrict.SensitiveCall("terminal", args); !sensitive {
+ t.Fatal("terminal 必须被判定为敏感操作(否则代审链根本不会触发)")
+ }
+ reviewer := &approvalReviewer{allowed: true}
+ gate := restrict.NewGate(reviewer, func(context.Context) (string, string) { return "web", "昔涟" })
+ decision := gate.Admit(ctx, "terminal", args)
+ if !decision.Allow || decision.Approval == nil {
+ t.Fatalf("代审批准后应放行并留下记录: %+v", decision)
+ }
+ if reviewer.calls != 1 {
+ t.Fatalf("代审者调用次数 = %d, want 1", reviewer.calls)
+ }
+
+ srv.RecordApproval(ctx, *decision.Approval)
+
+ // ① 前端小字帧(design/11 §4 的固定句式)。
+ typ, raw := readWire(t, wsConn, "approval_notice")
+ if typ != wsApprovalNotice {
+ t.Fatalf("frame type = %q, want %q (%s)", typ, wsApprovalNotice, raw)
+ }
+ var frame struct {
+ Type string `json:"type"`
+ SessionID string `json:"sessionId"`
+ Data struct {
+ Actor string `json:"actor"`
+ Tool string `json:"tool"`
+ Op string `json:"op"`
+ Detail string `json:"detail"`
+ Explain string `json:"explain"`
+ Allowed bool `json:"allowed"`
+ At string `json:"at"`
+ } `json:"data"`
+ }
+ if err := json.Unmarshal(raw, &frame); err != nil {
+ t.Fatalf("decode frame %s: %v", raw, err)
+ }
+ if frame.SessionID != "web" {
+ t.Fatalf("frame sessionId = %q, want web(小字要投到发生代审的那个会话)", frame.SessionID)
+ }
+ if frame.Data.Explain != "「昔涟 想要干什么,我审查后批准了」" {
+ t.Fatalf("小字 = %q, want design/11 §4 的固定文案", frame.Data.Explain)
+ }
+ if frame.Data.Tool != "terminal" || frame.Data.Op != string(restrict.SensitiveExecCommand) || !frame.Data.Allowed {
+ t.Fatalf("小字帧字段 = %+v", frame.Data)
+ }
+ if frame.Data.Detail == "" {
+ t.Fatal("小字帧应带动作摘要(detail),前端可作副文本")
+ }
+ if _, err := time.Parse(time.RFC3339Nano, frame.Data.At); err != nil {
+ t.Fatalf("帧时间戳 %q 不是 RFC3339Nano: %v", frame.Data.At, err)
+ }
+
+ // ② 审计链里有行(design/11 §8:代审动作批准/拒绝各落一行)。
+ rows := readAuditRows(t, ctx, conn)
+ if len(rows) != 1 {
+ t.Fatalf("audit_logs 行数 = %d, want 1 (%+v)", len(rows), rows)
+ }
+ got := rows[0]
+ if got.who != "昔涟" || got.what != "approval.terminal" || got.result != approvalResultGrant {
+ t.Fatalf("审计行 = %+v, want {昔涟 approval.terminal granted}", got)
+ }
+}
+
+// TestRecordApproval_DeniedLandsAsDeniedRow 锁定拒绝路径同样落一行
+// (result=denied),且小字换成「我审查后拒绝了」。
+func TestRecordApproval_DeniedLandsAsDeniedRow(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ srv, url, jwt, conn := newApprovalEnv(t)
+ wsConn := ownerWSConn(t, url, signAny(t, jwt, "acct", auth.RoleOwner))
+
+ gate := restrict.NewGate(&approvalReviewer{allowed: false},
+ func(context.Context) (string, string) { return "web", "昔涟" })
+ decision := gate.Admit(ctx, "terminal", map[string]any{"command": "rm -rf /"})
+ if decision.Allow {
+ t.Fatalf("代审拒绝却放行: %+v", decision)
+ }
+ srv.RecordApproval(ctx, *decision.Approval)
+
+ if typ, raw := readWire(t, wsConn, "denied notice"); typ != wsApprovalNotice {
+ t.Fatalf("frame type = %q, want %q (%s)", typ, wsApprovalNotice, raw)
+ }
+ rows := readAuditRows(t, ctx, conn)
+ if len(rows) != 1 || rows[0].result != approvalResultDeny {
+ t.Fatalf("审计行 = %+v, want 一行 result=denied", rows)
+ }
+}
+
+// TestRecordApproval_NoticeReachesOwnerNotViewer 锁定 design/11 §7.1 的帧门:
+// 代审小字是**内容帧**(带角色名与动作),因此只有 owner/admin 收得到,
+// viewer(只读监控档)收不到——新帧默认 fail-closed,未进状态机信号白名单。
+func TestRecordApproval_NoticeReachesOwnerNotViewer(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ srv, url, jwt, _ := newApprovalEnv(t)
+ viewer := dialWS(t, url, signAny(t, jwt, "viewer", auth.RoleViewer))
+ t.Cleanup(func() { viewer.Close() })
+ owner := ownerWSConn(t, url, signAny(t, jwt, "acct", auth.RoleOwner))
+ waitConnCount(t, srv, 2)
+
+ srv.RecordApproval(ctx, restrict.ApprovalEvent{
+ SessionID: "web",
+ Actor: "昔涟",
+ Tool: "terminal",
+ Op: restrict.SensitiveExecCommand,
+ Detail: "terminal echo hi",
+ Explain: "「昔涟 想要干什么,我审查后批准了」",
+ Allowed: true,
+ At: time.Now(),
+ })
+
+ if typ, raw := readWire(t, owner, "owner notice"); typ != wsApprovalNotice {
+ t.Fatalf("owner 未收到小字帧: %q (%s)", typ, raw)
+ }
+ // viewer 侧:本就不该有帧。给一个短窗口,任何帧都算失败
+ // (连接在读超时后会失效,所以这必须是该连接的最后一次读)。
+ _ = viewer.SetReadDeadline(time.Now().Add(wsRoleGateNoFrameWait))
+ if _, msg, err := viewer.ReadMessage(); err == nil {
+ t.Fatalf("viewer 收到了代审小字帧,违反 design/11 §7.1: %s", msg)
+ }
+}
+
+// auditRow 是 audit_logs 的一行(who/what/result)。
+type auditRow struct {
+ who string
+ what string
+ result string
+}
+
+// readAuditRows 读取 audit_logs 全部行(用例只写很少几行,无需分页)。
+func readAuditRows(t *testing.T, ctx context.Context, conn *sql.DB) []auditRow {
+ t.Helper()
+ rows, err := conn.QueryContext(ctx, `SELECT who, what, result FROM audit_logs ORDER BY id`)
+ if err != nil {
+ t.Fatalf("query audit_logs: %v", err)
+ }
+ defer rows.Close()
+ out := make([]auditRow, 0, 2)
+ for rows.Next() {
+ var r auditRow
+ if err := rows.Scan(&r.who, &r.what, &r.result); err != nil {
+ t.Fatalf("scan audit_logs: %v", err)
+ }
+ out = append(out, r)
+ }
+ if err := rows.Err(); err != nil {
+ t.Fatalf("iterate audit_logs: %v", err)
+ }
+ return out
+}
diff --git a/internal/services/gateway/admin_policy_persist_test.go b/internal/services/gateway/admin_policy_persist_test.go
new file mode 100644
index 0000000..c71e489
--- /dev/null
+++ b/internal/services/gateway/admin_policy_persist_test.go
@@ -0,0 +1,110 @@
+package gateway
+
+import (
+ "context"
+ "database/sql"
+ "io"
+ "log/slog"
+ "path/filepath"
+ "testing"
+
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+ capreg "git.yeij.top/AskaEth/Cyrene_v2/internal/capability/registry"
+ "git.yeij.top/AskaEth/Cyrene_v2/internal/db"
+)
+
+// 本文件锁定裁决 1.3/10.4.2 的管理面一侧:面板的「工具策略」保存
+// (POST /api/v1/admin/plugins/policy)真的**先落库再改内存**——重启后策略仍在。
+// 落盘载体是 tool_policies 表(迁移 0012_tool_policy),由 registry 的
+// PolicyStore 钩子写入;这里用真实 SQLite 库走完整 HTTP 路径。
+
+// policyEnv 接线一个「策略已接存储」的能力注册表的网关,返回服务端地址、
+// JWT 服务与库连接(用例直接查 tool_policies 断言落盘)。
+func policyEnv(t *testing.T) (string, *auth.JWTService, *sql.DB) {
+ t.Helper()
+ ctx := context.Background()
+ log := slog.New(slog.NewTextHandler(io.Discard, nil))
+ conn, err := db.Open(ctx, filepath.Join(t.TempDir(), "cyrene.db"), log)
+ if err != nil {
+ t.Fatalf("open sqlite: %v", err)
+ }
+ t.Cleanup(func() { conn.Close() })
+ if err := db.MigrateUp(ctx, conn, log); err != nil {
+ t.Fatalf("MigrateUp: %v", err)
+ }
+ store, err := capreg.NewSQLitePolicyStore(conn, log)
+ if err != nil {
+ t.Fatalf("policy store: %v", err)
+ }
+ reg := capreg.New()
+ if err := reg.AttachPolicyStore(ctx, store); err != nil {
+ t.Fatalf("AttachPolicyStore: %v", err)
+ }
+ if err := reg.RegisterTool(stubTool{}); err != nil {
+ t.Fatalf("register stub tool: %v", err)
+ }
+ _, ts, jwt := buildEnv(t, nil, Deps{Registry: reg})
+ return ts.URL, jwt, conn
+}
+
+// TestAdminSetPolicyPersistsToToolPolicies 锁定「面板保存 → 真落库」:
+// 走真实 HTTP 端点写入后,tool_policies 里有对应的行。
+func TestAdminSetPolicyPersistsToToolPolicies(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ url, jwt, conn := policyEnv(t)
+ owner := signAny(t, jwt, "acct", auth.RoleOwner)
+
+ resp, body := doReq(t, "POST", url+"/api/v1/admin/plugins/policy",
+ map[string]any{"name": "echo", "allowInGroup": true, "allowInStranger": false}, owner)
+ if resp.StatusCode != 200 {
+ t.Fatalf("POST policy status = %d, body = %s", resp.StatusCode, body)
+ }
+ var (
+ group bool
+ stranger bool
+ )
+ if err := conn.QueryRowContext(ctx,
+ `SELECT allow_in_group, allow_in_stranger FROM tool_policies WHERE name = 'echo'`).
+ Scan(&group, &stranger); err != nil {
+ t.Fatalf("tool_policies 里没有 echo 的策略行(未落盘?): %v", err)
+ }
+ if !group || stranger {
+ t.Fatalf("落盘策略 = {group:%v stranger:%v}, want {true false}", group, stranger)
+ }
+}
+
+// TestAdminSetPolicySurvivesRestart 跨「重启」验证:写完策略后另外构造一个
+// 注册表重新 Load,标记仍在(这正是裁决 1.3 要求消灭的「重启即失」)。
+func TestAdminSetPolicySurvivesRestart(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ url, jwt, conn := policyEnv(t)
+ owner := signAny(t, jwt, "acct", auth.RoleOwner)
+
+ if resp, body := doReq(t, "POST", url+"/api/v1/admin/plugins/policy",
+ map[string]any{"name": "echo", "allowInGroup": false, "allowInStranger": true}, owner); resp.StatusCode != 200 {
+ t.Fatalf("POST policy status = %d, body = %s", resp.StatusCode, body)
+ }
+
+ // 模拟重启:新注册表 + 新 store,只有 Load 一条路能拿到刚才的标记。
+ log := slog.New(slog.NewTextHandler(io.Discard, nil))
+ store, err := capreg.NewSQLitePolicyStore(conn, log)
+ if err != nil {
+ t.Fatalf("policy store (2): %v", err)
+ }
+ rebooted := capreg.New()
+ if err := rebooted.AttachPolicyStore(ctx, store); err != nil {
+ t.Fatalf("AttachPolicyStore (2): %v", err)
+ }
+ if err := rebooted.RegisterTool(stubTool{}); err != nil {
+ t.Fatalf("RegisterTool (2): %v", err)
+ }
+ pol, err := rebooted.Policy("echo")
+ if err != nil {
+ t.Fatalf("Policy (2): %v", err)
+ }
+ if pol.AllowInGroup || !pol.AllowInStranger {
+ t.Fatalf("重启后策略 = %+v, want {group:false stranger:true}", pol)
+ }
+}