pionxe · pionxe · Apr 11, 2026 · Apr 11, 2026
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -58,6 +58,7 @@ graph TD
     subgraph "Infrastructure Layer 基础设施层"
         PROV["Provider"]
         TOOL["Tool"]
+        SEC["Security"]
     end
 
     subgraph "Support Layer 支撑层"
@@ -76,6 +77,7 @@ graph TD
     LOOP <--> SESS
     LOOP ==> PROV
     LOOP ==> TOOL
+    TOOL <--> SEC
 
     CTX -. "依赖" .-> UTIL
     TOOL -. "依赖" .-> UTIL
@@ -92,6 +94,7 @@ graph TD
 - Runtime MUST 作为唯一编排中心，负责链路生命周期与终态收敛。
 - Provider MUST 吸收模型厂商差异，向上游输出统一协议。
 - Tools MUST 作为工具执行边界，负责权限与结果归一。
+- Security MUST 作为统一权限治理边界，负责策略命中、审批事件与会话级记忆。
 - Utils MUST 通过 `utils.Registry` 契约提供统一辅助能力入口。
 
 ## 5. 模块职责矩阵（逻辑依赖 + 契约关系）
@@ -103,6 +106,7 @@ graph TD
 | Context | Prompt 组装、上下文压缩、作用域隔离 | Runtime | Config / Utils | `context.BuildInput`、`context.BuildResult` |
 | Provider | 模型协议抹平、流式事件归一、能力判定 | Runtime | 模型供应商 API | `provider.GenerateRequest`、`provider.StreamEvent` |
 | Tools | 工具执行、审批拦截、输出归一 | Runtime | 本地/远端执行器 | `tools.ToolCallInput`、`tools.ToolResult` |
+| Security | 权限判定、审批事件、session 记忆、工作区边界复核 | Tools / Runtime | 策略规则与审批交互 | `security.Action`、`security.CheckResult` |
 | Session | 会话持久化、摘要视图、状态恢复 | Runtime | 存储介质 | `session.Store`、`session.Session`、`session.SessionSummary` |
 | Config | 配置加载、校验、更新、快照提供 | Runtime / Gateway | 配置文件与环境变量 | `config.Registry` |
 | Utils | 通用辅助能力（Token/路径/解析/序列化） | Gateway / Runtime / Context / Tools | 基础库 | `utils.Registry` |
@@ -126,6 +130,7 @@ graph TD
 | `Runtime -> Context` | `context.BuildInput`、`context.AdvancedBuildInput` | `context.BuildResult` | 编排层请求上下文构建 |
 | `Runtime -> Provider` | `provider.GenerateRequest` | `provider.StreamEvent` | 模型生成调用与流式事件回传 |
 | `Runtime -> Tools` | `tools.ToolCallInput` | `tools.ToolResult` | 工具执行与结果回灌 |
+| `Tools / Runtime -> Security` | `security.Action` / `runtime.PermissionResolutionInput` | `security.CheckResult` / 审批事件 | 权限判定、审批闭环、session 记忆 |
 | `Runtime <-> Session` | `session.Store` | `session.Session`、`session.SessionSummary` | 会话读写与摘要查询 |
 | `Runtime <-> Config` | `config.Registry` | `config.Config` | 配置读取与更新事务 |
 | `Runtime/Context/Tools/Gateway -> Utils` | `utils.Registry` | 各子能力接口返回值 | 统一辅助能力调用入口 |
@@ -148,11 +153,10 @@ graph TD
 
 1. 先读本文档：系统边界、单入口链路、契约映射。
 2. 再读核心编排：`runtime`、`session`。
-3. 再读协议与执行：`context`、`provider`、`tools`、`config`。
+3. 再读协议与执行：`context`、`provider`、`tools`、`security`、`config`。
 4. 最后读入口与支撑：`gateway`、`tui`、`cli`、`utils`。
 
 ---
 
 本文档仅承载系统级架构定义。模块级实现细节请查看对应模块文档。
 
-
diff --git a/docs/architecture/security/README.md b/docs/architecture/security/README.md
@@ -0,0 +1,195 @@
+# Security 模块设计与接口文档
+
+> 文档版本：v1.0
+> 文档定位：详细设计文档（LLD）+ 接口文档（API/Contract）
+
+## 规范词约定
+
+- `MUST`：必须满足的架构契约，违反会破坏权限治理闭环与执行安全。
+- `SHOULD`：强烈建议遵循，若例外必须记录原因。
+- `MAY`：可选增强能力。
+
+## 1. 详细设计（LLD）
+
+### 1.1 目的与范围
+
+Security 模块是 Tools / Runtime 之间的统一安全治理边界，负责权限策略命中、审批事件透传、session 级记忆与工作区边界复核。
+
+Security 模块 MUST 覆盖：
+
+- 动作抽象与统一权限输入。
+- allow / ask / deny 策略命中。
+- session 级 `once / always_session / reject_session` 记忆。
+- `PermissionRequest / PermissionResolved` 事件发布。
+- 工作区与 sandbox 复核。
+
+Security 模块 MUST NOT 覆盖：
+
+- 具体工具执行（由 Tools 负责）。
+- 主循环控制（由 Runtime 负责）。
+- TUI 审批交互界面实现（由 TUI / Gateway 负责）。
+
+### 1.2 架构链路定位
+
+- Security 的直接上游 SHOULD 是 Tools，Runtime 在 ask 闭环中参与审批回传。
+- Client 不得直接调用 Security 判定能力。
+- 单入口链路中关键路径为 `Runtime -> Tools -> Security -> Tools -> Runtime`。
+
+### 1.3 模块边界
+
+- 上游：Tools、Runtime。
+- 下游：静态策略规则、session 记忆存储、工作区边界校验。
+- 边界约束：Security 仅返回 `CheckResult` 与审批事件，不负责直接执行工具。
+- 边界约束：Security 不得感知 Provider 协议细节。
+
+### 1.4 权限判定流程（当前/目标共性）
+
+```mermaid
+sequenceDiagram
+    participant TL as Tools
+    participant SG as Security Gateway
+    participant PM as PolicyMatcher
+    participant MEM as PermissionMemoryStore
+    participant SB as Workspace Check
+
+    TL->>SG: Evaluate(Action)
+    SG->>PM: Match(Action)
+    PM-->>SG: allow / ask / deny
+    SG->>MEM: Resolve(sessionID, action)
+    MEM-->>SG: remembered / miss
+    SG->>SB: validate workspace / sandbox
+    SB-->>SG: pass / fail
+    SG-->>TL: CheckResult
+```
+
+### 1.5 ask 审批闭环（目标态）
+
+```mermaid
+sequenceDiagram
+    participant TL as Tools
+    participant SG as Security Gateway
+    participant EV as PermissionEventPublisher
+    participant RT as Runtime
+    participant UI as TUI/Gateway
+
+    TL->>SG: Evaluate(Action)
+    SG-->>TL: CheckResult(decision=ask)
+    SG->>EV: PublishPermissionRequest
+    EV-->>RT: permission_request
+    RT-->>UI: permission_request
+    UI-->>RT: user decision
+    RT->>SG: Remember(sessionID, action, resolution)
+    SG->>EV: PublishPermissionResolved
+    EV-->>RT: permission_resolved
+```
+
+### 1.6 核心语义
+
+- `allow`：允许直接执行。
+- `deny`：阻断执行，并返回稳定错误语义。
+- `ask`：要求上游发起显式审批闭环。
+- `once`：仅当前一次请求生效。
+- `always_session`：当前 session 内同范围请求持续放行。
+- `reject_session`：当前 session 内同范围请求持续拒绝。
+
+### 1.7 非功能约束
+
+- 安全性：硬性 deny 规则 MUST 不被宽泛的 session allow 记忆绕过。
+- 一致性：审批事件字段 SHOULD 可观测、可回放、可用于 UI 展示。
+- 可替换性：策略命中、session 存储、事件发布 SHOULD 通过接口解耦。
+- 可扩展性：未来 bash / filesystem / webfetch / MCP 的命中策略 SHOULD 共享统一 Action 模型。
+
+## 2. 接口文档（API/Contract）
+
+### 2.1 公共规范
+
+- 所有判定方法 MUST 接收 `context.Context`。
+- Security 对外 SHOULD 通过 `Action -> CheckResult` 建模。
+- ask 场景 MUST 可序列化为稳定事件与审批决议结构。
+
+### 2.2 接口目录
+
+| 接口 | 职责 |
+|---|---|
+| `PolicyMatcher` | 命中策略层 |
+| `PermissionMemoryStore` | session 级记忆层 |
+| `PermissionEventPublisher` | 审批事件透传层 |
+| `ToolSecurityGateway` | 统一安全网关 |
+
+### 2.3 关键类型目录
+
+| 类型 | 说明 |
+|---|---|
+| `Action` | 统一安全输入 |
+| `ActionPayload` | 权限检查上下文 |
+| `Rule` | 静态策略规则 |
+| `Decision` | allow / ask / deny |
+| `CheckResult` | 判定结果 |
+| `PermissionRequest` | 审批请求事件负载 |
+| `PermissionResolved` | 审批完成事件负载 |
+| `PermissionResolution` | 上游回写的审批决议 |
+
+### 2.4 跨层契约绑定
+
+| 链路 | 输入契约 | 输出契约 | 说明 |
+|---|---|---|---|
+| `Tools -> Security` | `security.Action` | `security.CheckResult` | 工具执行前权限判定 |
+| `Runtime -> Security` | `security.PermissionResolution` | `PermissionResolved` 事件 | 审批结果回写与记忆更新 |
+| `Security -> Runtime/TUI` | `PermissionRequest` / `PermissionResolved` | 运行时事件 | ask 闭环可观测化 |
+
+### 2.5 JSON 示例
+
+#### 2.5.1 Action 示例
+
+```json
+{
+  "type": "read",
+  "payload": {
+    "tool_name": "read_file",
+    "resource": "filesystem_read",
+    "operation": "read",
+    "session_id": "sess_123",
+    "workdir": "C:/workspace/demo",
+    "target_type": "path",
+    "target": "README.md"
+  }
+}
+```
+
+#### 2.5.2 CheckResult 示例
+
+```json
+{
+  "decision": "ask",
+  "reason": "reading target outside current trusted scope",
+  "rule": {
+    "id": "ask-filesystem-outside-workspace",
+    "resource": "filesystem_read"
+  }
+}
+```
+
+#### 2.5.3 PermissionResolution 示例
+
+```json
+{
+  "request_id": "perm_001",
+  "allowed": true,
+  "reason": "user approved in tui",
+  "scope": "always_session"
+}
+```
+
+### 2.6 变更规则
+
+- 新增策略字段 MUST 向后兼容。
+- 记忆范围新增 SHOULD 通过扩展枚举，不复用已有语义。
+- ask 相关事件字段调整 MUST 保持上游可判定性。
+
+## 3. 评审检查清单
+
+- 是否把权限判定、审批事件、session 记忆拆成独立职责。
+- 是否明确 Security 不直接执行工具。
+- 是否明确 ask 闭环与 session remember 的目标语义。
+- 是否为 Tools / Runtime 提供稳定契约，而不是暴露内部规则实现。
+- 是否与 `security/interface.go` 类型名一致。