docs(core): README 补第二批能力对齐章节(五级工具作用域/patch_file/原生视觉)

README.md

@@ -21,6 +21,7 @@
 | sd_project_role_models | 项目角色模型配置（同上迁入；下拉 codes 指 sd_role 字典 + llm_model(status=active)） |
 | pipeline_deliverables | 产线交付物（同上迁入；主要写入方 pipeline-bidding） |
 | pipeline_user_memory | 跨会话持久记忆（2026-09-10 多租户：加 org_id/user_id 归属列，key 掺租户维度，迁移 m0023） |
+| pipeline_tool_policies | 工具作用域策略（2026-09-10 五级作用域 org/pipeline/role/project 的 allow/deny 微调，迁移 m0028） |
 
 ## 跨产线共享资源（wwwroot/api/）
 
@@ -86,3 +87,51 @@ user+scope+scope_id)，同内容跨租户 key 不同、唯一索引永不碰撞
 **ToolDefinition.required 字段（2026-09-10）**：None=旧行为（全参数必填），含可选
 参数的工具须显式声明 required 列表，否则 `to_openai_schema()` 把可选参数标成
 required、LLM 被迫为每个参数编值。GENERAL_TOOLS 全部带可选参数的工具已补 required。
+
+## 第二批能力对齐：五级工具作用域 + patch_file + 原生视觉（2026-09-10）
+
+### 五级作用域工具解析（tool_sources.py，GENERAL_TOOLS 30 个）
+
+用户要求：全局/机构/产线/角色/项目五级各注册不同工具，产线特有工具按产线区分。
+
+| 级 | 工具来源 | 隔离机制 |
+|---|---|---|
+| global | GENERAL_TOOLS | generic 会话剔除 project/data 类 |
+| org | 机构技能包 capability 工具 + 策略表 allow/deny | 技能 get_merged 按 orgs/{org}/ 物理目录隔离 |
+| pipeline | PipelineAbility.tools + 产线技能 capability 工具 | 注册表按 pipeline_id；generic 不挂 |
+| role | RoleSpec.tools 白名单（过滤器非添加器）+ 角色策略 | get_role_spec(pipeline_id, role) 按产线隔离 |
+| project | 策略表 allow/deny 微调 | 策略行 scope_id=project_id |
+
+- **策略表 pipeline_tool_policies**（scope/scope_id/tool_name/effect/reason/status，
+  uk(scope,scope_id,tool_name)）：CRUD 管理页 `/pipeline_core/pipeline_tool_policies/`；
+  表缺失/查询失败按无策略降级（WARN 日志，不阻断会话）。
+- **capability 两层语义**（别简化成一层）：①「capability 含哪些工具」映射从全部
+  可见技能收集（all/ 概念规范技能=映射手册）；②「本会话需要哪些 capability」只认
+  org/pipeline/role/project/user 层技能的声明——global 层声明不作为注入依据，
+  否则 generic 会话经 all/ 概念技能拿到 ~70 个产线工具、击穿七层隔离（单测有回归用例）。
+- **role 白名单收窄顺序**：capability 工具必须先并入再收窄（白名单作用于全集），
+  且白名单是过滤器不是添加器；ask_user/todo/memory/read_file/write_file 等基础工具始终保留。
+- 执行层强制门禁（service `_execute_tool`）：LLM 幻觉调用作用域外工具名直接拒绝
+  并回可行动提示——schema 防线挡不住幻觉。
+- 测试机实测：服务端直调 17/17（真实策略表读写/产线区分 sdlc 72 个 vs bidding 17 个
+  capability 工具/门禁三态）+ HTTP 门禁确认（generic 会话 schema 无 create_project，
+  LLM 如实告知未挂载拒绝伪造调用）。
+
+### patch_file 工具（文件定点替换）
+
+old_string 唯一性校验（0 次/多次拒绝，replace_all 显式放行）+ 原子写 + 越界防护
++ 二进制拒绝。HTTP 实测：agent 真实完成 write_file→patch_file→read_file 三步链并回读验证。
+
+### 原生视觉（上传图片直接进对话）
+
+- upload_tools：`is_image` + `build_image_parts`（OpenAI 多模态 data URL；8MB/张、
+  4 张/条上限，超限显式告知绝不静默丢）。
+- 三个 dspy 入口图片分流：不进文本上下文（避免「二进制无法读取」矛盾提示），
+  仍落盘工作空间（i2t 可再处理）。
+- gateway.run_message(image_paths) → executor.run(image_parts)：首条用户消息构造
+  多模态 content 数组；llm_bridge→llm_v1 端点→inference 全链原样透传 messages。
+- 降级兜底 `_degrade_images_if_needed`：模型不支持视觉时剥离图片重试一次 + 注入
+  系统说明让 LLM 如实告知「当前模型看不了图」，绝不假装看过。token 估算/压缩摘要
+  兼容 list content（`_content_as_text`）。
+- HTTP 严格实测：中性文件名（img_001/img_002，无颜色词）红蓝两图一条消息，
+  agent 答「第一张红色、第二张蓝色」映射正确，degrade 日志 0 条（模型原生支持）。