Clarify legacy personal settings compatibility

Why: An empty setting scope must not imply shared-project or system authority.

Evidence: Documentation-only clarification of the verified scope contract.

Impact: No runtime change; retain fail-closed shared settings semantics.

Refs: P1, docs/records/2026-10-14-rdm-settings-completion-contract.md

profile.go

@@ -1,45 +1,48 @@
 package core
 
-import "encoding/json"
+import (
+	"encoding/json"
+	"strings"
+)
 
 // 智能体画像（4.7）：核心定制机制，全部数据化、可导入导出。
 type AgentProfile struct {
-	ID          string         `json:"id"`
-	Owner       string         `json:"owner,omitempty"` // 租户；空 = 共享（builtin）
-	Name        string         `json:"name"`
-	Description string         `json:"description,omitempty"`
-	Builtin     bool           `json:"builtin,omitempty"`
-	Source      string         `json:"source,omitempty"` // builtin | plugin | user
-	SystemPrompt string        `json:"systemPrompt"`
+	ID           string `json:"id"`
+	Owner        string `json:"owner,omitempty"` // 租户；空 = 共享（builtin）
+	Name         string `json:"name"`
+	Description  string `json:"description,omitempty"`
+	Builtin      bool   `json:"builtin,omitempty"`
+	Source       string `json:"source,omitempty"` // builtin | plugin | user
+	SystemPrompt string `json:"systemPrompt"`
 	// PromptModules 引用提示词库模块 ID（有序；空 = 组装默认基座全集）。
 	// SystemPrompt 兼容保留：非空时作为附加段追加在模块组装结果之后。
 	PromptModules []string      `json:"promptModules,omitempty"`
-	Model       ModelRoute     `json:"model"`
-	Tools       ToolPolicy     `json:"tools"`
-	Context     ContextPolicy  `json:"context"`
-	HITL        HITLPolicy     `json:"hitl"`
-	Budget      RunBudget      `json:"budget"`
+	Model         ModelRoute    `json:"model"`
+	Tools         ToolPolicy    `json:"tools"`
+	Context       ContextPolicy `json:"context"`
+	HITL          HITLPolicy    `json:"hitl"`
+	Budget        RunBudget     `json:"budget"`
 }
 
 // ModelRoute 按用途选择模型（4.7 kind 路由）：空串回落到 chat 默认。
 type ModelRoute struct {
-	Chat       string `json:"chat,omitempty"`
+	Chat        string `json:"chat,omitempty"`
 	Lightweight string `json:"lightweight,omitempty"`
-	Embedding  string `json:"embedding,omitempty"`
-	Rerank     string `json:"rerank,omitempty"`
+	Embedding   string `json:"embedding,omitempty"`
+	Rerank      string `json:"rerank,omitempty"`
 }
 
 // ToolPolicy 三清单：allow/deny 决定可见工具，confirm 强制执行前 HITL 确认。
 // 匹配语义：精确名或前缀通配（"http.*" 表示 http 前缀）；deny 优先于 allow。
 type ToolPolicy struct {
-	Allow   []string `json:"allow"`   // ["*"] 全部
+	Allow   []string `json:"allow"` // ["*"] 全部
 	Deny    []string `json:"deny,omitempty"`
 	Confirm []string `json:"confirm,omitempty"`
 }
 
 // ContextPolicy（4.10）：ctxasm 的输入；逐版本增加策略项不动组装器接口。
 type ContextPolicy struct {
-	MaxHistoryMessages int  `json:"maxHistoryMessages"` // 0 = 默认 40
+	MaxHistoryMessages int  `json:"maxHistoryMessages"`        // 0 = 默认 40
 	SummarizeBeyond    bool `json:"summarizeBeyond,omitempty"` // 远期；先存标志
 	MemoryBudgetPct    int  `json:"memoryBudgetPct,omitempty"` // 注入槽份额上限
 	KnowledgeBudgetPct int  `json:"knowledgeBudgetPct,omitempty"`
@@ -102,11 +105,27 @@ const (
 type SettingEffect string
 
 const (
-	EffectHot    SettingEffect = "hot"      // 立即生效
-	EffectNewRun SettingEffect = "new-run"  // 仅影响新 run
+	EffectHot     SettingEffect = "hot"     // 立即生效
+	EffectNewRun  SettingEffect = "new-run" // 仅影响新 run
 	EffectRestart SettingEffect = "restart" // 需重启
 )
 
+// SettingScope 声明设置项的写入归属（提案 2026-10-13-rdm-settings-members-duties-perms-increment P2）。
+// 空串保留旧个人配置兼容，不表示共享项目策略或系统管理资格。
+type SettingScope string
+
+const (
+	// SettingScopeSystem 受管项：仅系统管理面（admin）可写；user/project 写入被拒，
+	// 生效链忽略这两层的存量覆盖值。
+	SettingScopeSystem SettingScope = "system"
+	// SettingScopeUser is a private account preference, never a shared project policy.
+	SettingScopeUser SettingScope = "user"
+	// SettingScopeProject is shared business configuration under project authority.
+	SettingScopeProject SettingScope = "project"
+	// SettingScopeProjectPersonal is a private preference within one project.
+	SettingScopeProjectPersonal SettingScope = "project-personal"
+)
+
 // SettingDesc 描述一个设置项；设置页按此渲染并标注生效时机（schema 驱动）。
 type SettingDesc struct {
 	Key         string        `json:"key"`
@@ -118,6 +137,117 @@ type SettingDesc struct {
 	Options     []string      `json:"options,omitempty"` // enum
 	Effect      SettingEffect `json:"effect"`
 	Secret      bool          `json:"secret,omitempty"`
+	Scope       SettingScope  `json:"scope,omitempty"` // Empty is legacy personal compatibility; explicit scopes own their write surface.
+}
+
+// ManagedPaths 返回 schema 中 scope=system 的键路径（点路径形式）。
+func ManagedPaths(descs []SettingDesc) []string {
+	out := make([]string, 0, len(descs))
+	for _, d := range descs {
+		if d.Scope == SettingScopeSystem {
+			out = append(out, d.Key)
+		}
+	}
+	return out
+}
+
+// FlattenSettingLeafPaths 列出 values 的全部叶子点路径。子树为标量或数组时该子树
+// 根即叶子。用于受管触碰检测：深合并语义下叶子决定最终覆盖面。
+func FlattenSettingLeafPaths(values map[string]any) []string {
+	var out []string
+	var walk func(prefix string, m map[string]any)
+	walk = func(prefix string, m map[string]any) {
+		for k, v := range m {
+			path := k
+			if prefix != "" {
+				path = prefix + "." + k
+			}
+			if vm, ok := v.(map[string]any); ok && len(vm) > 0 {
+				walk(path, vm)
+				continue
+			}
+			out = append(out, path)
+		}
+	}
+	walk("", values)
+	return out
+}
+
+// pathTouchesManaged 判断 path 是否触碰 managed：等于受管路径、位于受管子树内
+// （受管路径是 path 的前缀），或整体覆盖受管子树（path 是受管路径的前缀——
+// 标量覆盖整棵受管 map 同样破坏受管值）。
+func pathTouchesManaged(path string, managed []string) bool {
+	for _, mp := range managed {
+		if path == mp ||
+			strings.HasPrefix(path, mp+".") ||
+			strings.HasPrefix(mp, path+".") {
+			return true
+		}
+	}
+	return false
+}
+
+// TouchesManagedSettings 返回 values 中触碰受管路径的叶子；空切片 = 无触碰。
+// 调用方须传入已展开点路径的嵌套 map（normalize 后）。
+func TouchesManagedSettings(values map[string]any, managed []string) []string {
+	var hits []string
+	for _, p := range FlattenSettingLeafPaths(values) {
+		if pathTouchesManaged(p, managed) {
+			hits = append(hits, p)
+		}
+	}
+	return hits
+}
+
+// StripManagedSettings 返回删除受管路径后的浅拷贝（不改入参）。受管路径的祖先
+// 若因此只剩空 map 一并删除。入参须为嵌套形式（点路径已展开）。
+func StripManagedSettings(values map[string]any, managed []string) map[string]any {
+	if len(values) == 0 || len(managed) == 0 {
+		return values
+	}
+	// 叶子命中或祖先整体命中都删；逐叶子重建最简单可靠。
+	leaves := FlattenSettingLeafPaths(values)
+	keep := map[string]any{}
+	for _, leaf := range leaves {
+		if pathTouchesManaged(leaf, managed) {
+			continue
+		}
+		setPath(keep, leaf, lookupAny(values, leaf))
+	}
+	return keep
+}
+
+func setPath(m map[string]any, path string, val any) {
+	parts := strings.Split(path, ".")
+	cur := m
+	for i, p := range parts {
+		if i == len(parts)-1 {
+			cur[p] = val
+			return
+		}
+		next, ok := cur[p].(map[string]any)
+		if !ok {
+			next = map[string]any{}
+			cur[p] = next
+		}
+		cur = next
+	}
+}
+
+func lookupAny(m map[string]any, path string) any {
+	parts := strings.Split(path, ".")
+	var cur any = m
+	for _, p := range parts {
+		cm, ok := cur.(map[string]any)
+		if !ok {
+			return nil
+		}
+		cur, ok = cm[p]
+		if !ok {
+			return nil
+		}
+	}
+	return cur
 }
 
 // EffectiveSettings 是覆盖链（system → user → project → conversation）深合并结果。

settings_scope_test.go

@@ -0,0 +1,85 @@
+package core
+
+import (
+	"reflect"
+	"sort"
+	"testing"
+)
+
+func TestManagedPathsFiltersSystemScope(t *testing.T) {
+	descs := []SettingDesc{
+		{Key: "models.chat.model", Scope: SettingScopeSystem},
+		{Key: "ui.theme"},
+		{Key: "tools.tavily.apiKeys", Scope: SettingScopeSystem},
+	}
+	got := ManagedPaths(descs)
+	sort.Strings(got)
+	want := []string{"models.chat.model", "tools.tavily.apiKeys"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("ManagedPaths = %v, want %v", got, want)
+	}
+}
+
+func TestTouchesManagedSettings(t *testing.T) {
+	managed := []string{"models.chat.model", "tools.tavily.apiKeys", "telemetry.otlpEndpoint"}
+	cases := []struct {
+		name string
+		in   map[string]any
+		want []string
+	}{
+		{"exact leaf", map[string]any{"models": map[string]any{"chat": map[string]any{"model": "x"}}}, []string{"models.chat.model"}},
+		{"sibling untouched", map[string]any{"models": map[string]any{"chat": map[string]any{"baseUrl": "x"}}}, nil},
+		{"ancestor scalar overwrite", map[string]any{"models": "oops"}, []string{"models"}},
+		{"subtree inside managed", map[string]any{"telemetry": map[string]any{"otlpEndpoint": "http://x"}}, []string{"telemetry.otlpEndpoint"}},
+		{"other group untouched", map[string]any{"ui": map[string]any{"theme": "light"}}, nil},
+		{"empty map", map[string]any{}, nil},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := TouchesManagedSettings(tc.in, managed)
+			sort.Strings(got)
+			if tc.want == nil && len(got) != 0 {
+				t.Fatalf("TouchesManagedSettings = %v, want none", got)
+			}
+			if tc.want != nil && !reflect.DeepEqual(got, tc.want) {
+				t.Fatalf("TouchesManagedSettings = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+func TestStripManagedSettings(t *testing.T) {
+	managed := []string{"models.chat.model", "models.chat.apiKey"}
+	in := map[string]any{
+		"models": map[string]any{
+			"chat":        map[string]any{"model": "x", "baseUrl": "https://b"},
+			"lightweight": map[string]any{"model": "y"},
+		},
+		"ui": map[string]any{"theme": "dark"},
+	}
+	got := StripManagedSettings(in, managed)
+	want := map[string]any{
+		"models": map[string]any{
+			"chat":        map[string]any{"baseUrl": "https://b"},
+			"lightweight": map[string]any{"model": "y"},
+		},
+		"ui": map[string]any{"theme": "dark"},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("StripManagedSettings = %v, want %v", got, want)
+	}
+	if in["models"].(map[string]any)["chat"].(map[string]any)["model"] != "x" {
+		t.Fatal("StripManagedSettings 不应修改入参")
+	}
+}
+
+func TestStripManagedSettingsWholeSubtree(t *testing.T) {
+	managed := []string{"models.chat.model", "models.chat.baseUrl", "models.chat.apiKey", "models.chat.fallbacks"}
+	in := map[string]any{
+		"models": map[string]any{"chat": map[string]any{"model": "x", "baseUrl": "b", "apiKey": "k"}},
+	}
+	got := StripManagedSettings(in, managed)
+	if len(got) != 0 {
+		t.Fatalf("整棵受管子树应被剥除（含空父），got %v", got)
+	}
+}

ts/types.ts

@@ -269,6 +269,8 @@ export interface SettingDesc {
   default?: unknown; options?: string[];
   effect: 'hot' | 'new-run' | 'restart';
   secret?: boolean;
+  /** Setting ownership; an omitted scope retains legacy personal compatibility. */
+  scope?: 'system' | 'user' | 'project' | 'project-personal';
 }
 
 // ---- 插件 ----