feat(agents): add Undefined self code inspection agent

ARCHITECTURE.md

@@ -112,11 +112,12 @@ graph TB
             TS_Memes["memes.*<br/>• search_memes<br/>• send_meme_by_uid"]
         end
 
-        subgraph IntelligentAgents["智能体 Agents (skills/agents/, 6个)"]
+        subgraph IntelligentAgents["智能体 Agents (skills/agents/, 7个)"]
             A_Info["info_agent<br/>信息查询助手<br/>(18个工具)<br/>• weather_query<br/>• *hot 热搜<br/>• bilibili_*<br/>• arxiv_search<br/>• whois"]
             A_Web["web_agent<br/>网络搜索助手<br/>(3个工具 + MCP)<br/>• web_search<br/>• crawl_webpage<br/>• Playwright MCP"]
             A_File["file_analysis_agent<br/>文件分析助手<br/>(14个工具)<br/>• extract_* (PDF/Word/Excel/PPT)<br/>• analyze_code<br/>• analyze_multimodal"]
             A_Naga["naga_code_analysis_agent<br/>NagaAgent 代码分析<br/>(7个工具)<br/>• read_file / glob<br/>• search_file_content"]
+            A_Self["undefined_self_code_agent<br/>Undefined 自身代码查阅<br/>(4个工具)<br/>• read_file / list_directory<br/>• glob / search_file_content"]
             A_Entertainment["entertainment_agent<br/>娱乐助手<br/>(9个工具)<br/>• ai_draw_one<br/>• horoscope<br/>• video_random_recommend"]
             A_Code["code_delivery_agent<br/>代码交付助手<br/>(13个工具)<br/>• Docker 容器隔离<br/>• Git 仓库克隆<br/>• 代码编写验证<br/>• 打包上传"]
         end
@@ -331,7 +332,7 @@ graph TB
     class Dir_History,Dir_FAQ,Dir_TokenUsage,Dir_Cognitive,File_Memory,File_EndSummary,File_ScheduledTasks,Dir_Logs,File_Config persistence
     class Prompts,Intros resource
     class QueueManager,ModelQueues,DispatcherLoop queue
-    class A_Info,A_Web,A_File,A_Naga,A_Entertainment,A_Code agent
+    class A_Info,A_Web,A_File,A_Naga,A_Self,A_Entertainment,A_Code agent
 ```
 
 ## 二、数据流向图
@@ -493,6 +494,7 @@ graph TB
             WebAgent["web_agent<br/>网络搜索<br/>• MCP Playwright"]
             FileAgent["file_analysis_agent<br/>文件分析"]
             NagaAgent["naga_code_analysis_agent<br/>代码分析"]
+            SelfCodeAgent["undefined_self_code_agent<br/>自身代码查阅"]
             EntAgent["entertainment_agent<br/>娱乐"]
             CodeAgent["code_delivery_agent<br/>代码交付"]
         end
@@ -532,6 +534,7 @@ graph TB
     AgentToolReg --> WebAgent
     AgentToolReg --> FileAgent
     AgentToolReg --> NagaAgent
+    AgentToolReg --> SelfCodeAgent
     AgentToolReg --> EntAgent
 
     WebAgent --> MCPAgent
@@ -854,7 +857,7 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
     自动提取由 `PipelineRegistry` 并行检测、并行处理全部命中的管线；发送结果写入历史后继续进入 AI 自动回复。
 4. **AI 核心能力层**：AIClient (ai/client/ + client.py shim)、PromptBuilder (ai/prompts/ + prompts.py shim)、ModelRequester (ai/llm/ + llm.py shim)、ToolManager (tooling.py)、MultimodalAnalyzer (ai/multimodal/ + multimodal.py shim)、SummaryService (summaries.py)、TokenCounter (tokens.py)
 5. **存储与上下文层**：MessageHistoryManager (utils/history.py, 10000条限制)、MemoryStorage (memory.py, 置顶备忘录, 500条上限)、EndSummaryStorage、CognitiveService + JobQueue + HistorianWorker + VectorStore + ProfileStorage、MemeService + MemeWorker + MemeStore + MemeVectorStore (表情包库)、FAQStorage、ScheduledTaskStorage、TokenUsageStorage (自动归档)
-6. **技能系统层**：ToolRegistry (registry.py)、AgentRegistry、6个 Agents、11类 Toolsets
+6. **技能系统层**：ToolRegistry (registry.py)、AgentRegistry、7个 Agents、11类 Toolsets
 7. **异步 IO 层**：统一 IO 工具 (utils/io.py)，包含 write_json、read_json、append_line、跨平台文件锁 (flock/msvcrt)
 8. **数据持久化层**：历史数据目录、FAQ 目录、Token 归档目录、记忆文件、总结文件、定时任务文件
 
@@ -868,14 +871,15 @@ description: 从 PDF 文件中提取文本和表格，填写表单。当用户
 *   **优先级管理**：支持四级优先级（超级管理员 > 私聊 > 群聊@ > 群聊普通），确保重要消息优先响应。
 *   **关停收敛**：`MessageHandler.close()` 会先 flush `MessageBatcher`，再调用 `QueueManager.drain()` 等待已入队请求和在途请求自然完成，最后才停止队列处理器，避免缓冲消息只入队未执行。
 
-### 6个智能体 Agent
+### 7个智能体 Agent
 
 | Agent | 功能定位 | 工具数量 | 核心能力 |
 |-------|---------|---------|---------|
 | **info_agent** | 信息查询助手 | 18个 | 天气查询、热搜榜单、网络检测、B站信息查询、arXiv 搜索等 |
 | **web_agent** | 网络搜索助手 | 3个 + MCP | 网页搜索、爬虫、Playwright MCP |
 | **file_analysis_agent** | 文件分析助手 | 14个 | PDF/Word/Excel/PPT解析、代码分析、多模态分析 |
 | **naga_code_analysis_agent** | NagaAgent 代码分析 | 7个 | 代码库浏览、文件搜索、目录遍历 |
+| **undefined_self_code_agent** | Undefined 自身代码查阅 | 4个 | 受限读取源码、测试、文档、资源、脚本与 App |
 | **entertainment_agent** | 娱乐助手 | 9个 | AI 绘图、星座运势、小说搜索、随机视频推荐等 |
 | **code_delivery_agent** | 代码交付助手 | 13个 | Docker 隔离、仓库克隆、代码验证、打包上传 |
 

CHANGELOG.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+- 新增 `undefined_self_code_agent`，允许 AI 只读查阅 Undefined 自身源码、测试、文档、资源、脚本、配置示例和 App 实现；访问范围限制为指定目录和根目录公开文档，并补充主提示词路由、文档与测试。
+
+---
+
 ## v3.5.1 安全回复、群聊边界与配置表单优化
 
 本版本聚焦三个实际使用中的细节问题：一是群聊里只出现「你/我/他」等人称时，Undefined 更容易误判成在和自己说话；二是面对 prompt 注入或强行改人设的消息时，防御性回复有时过于模板化、攻击性过强，甚至在生成失败时仍会发送兜底脏话；三是 WebUI 配置页对枚举型字段的输入约束不足，容易让用户手填出不合法或不直观的配置值。v3.5.1 因此收紧对话归属判断，强化人设自洽与防注入边界，并把更多配置项改为下拉选择，降低误配置概率。

README.md

@@ -160,7 +160,7 @@ set_config(cfg)  # opt-in 注入全局单例；CLI 启动链不会调用
 
 # 自动扫描 skills/：tools + toolsets（end / group.* / cognitive.* …）
 tools = ToolRegistry()
-# 自动扫描 skills/agents/：web_agent、code_delivery_agent …
+# 自动扫描 skills/agents/：web_agent、undefined_self_code_agent、code_delivery_agent …
 agents = AgentRegistry()
 
 async def main() -> None:

docs/usage.md

@@ -118,9 +118,17 @@ Undefined 搭载了基于 ChromaDB 向量数据库的后台认知系统，无需
 
 ### `naga_code_analysis_agent` — NagaAgent 代码分析助手
 
-专门用于深度分析 NagaAgent 框架及本项目的源代码结构。
+专门用于深度分析 NagaAgent 框架的源代码结构。
 
-**子工具**：`read_file`、`search_code`、`analyze_structure`
+**子工具**：`read_file`、`list_directory`、`glob`、`search_file_content`、`read_naga_intro`
+
+---
+
+### `undefined_self_code_agent` — Undefined 自身代码查阅助手
+
+只读查阅 Undefined 当前仓库的源码、测试、文档、资源、脚本、配置示例和 App 实现。访问范围限制为 `src/`、`scripts/`、`tests/`、`res/`、`docs/`、`apps/` 以及根目录 `README.md`、`CHANGELOG.md`、`ARCHITECTURE.md`、`config.toml.example`。
+
+**子工具**：`read_file`、`list_directory`、`glob`、`search_file_content`
 
 ---
 

res/prompts/undefined.xml

@@ -819,6 +819,7 @@
 
       <strategy id="3">
         <name>善用工具</name>
+        <rule>需要查阅 Undefined 自身源码、测试、文档、资源、脚本、配置示例或 App 实现时，调用 undefined_self_code_agent</rule>
         <rule>需要了解图片内容时，调用 file_analysis_agent</rule>
         <rule>需要记住长期稳定的重要信息时，调用 memory.add（或 tools 列表中的对应名称）</rule>
         <rule>**不要主动调用无关工具**（天气、金价、新闻等），除非被明确要求</rule>
@@ -834,7 +835,7 @@
         <orchestration_rules>
           <rule>**先识别，再搜索，最后综合**：遇到图片/文件+问题的组合时，第一步只做内容识别，拿到识别结果后再决定是否需要搜索。</rule>
           <rule>**prompt 只描述 Agent 能力范围内的任务**：调用 file_analysis_agent 时 prompt 应该是"识别图中的游戏和角色名"，而不是"分析这个角色怎么养成"。</rule>
-          <rule>**不要指望 Agent 做它不擅长的事**：file_analysis_agent 没有搜索能力，不要让它回答需要外部知识的问题；web_agent 看不到图片，不要让它分析文件。</rule>
+          <rule>**不要指望 Agent 做它不擅长的事**：file_analysis_agent 没有搜索能力，不要让它回答需要外部知识的问题；web_agent 看不到图片，不要让它分析文件；undefined_self_code_agent 仅可只读查阅 Undefined 自身代码，不能写代码或执行命令。</rule>
           <rule>**你是指挥官，Agent 是专家**：你负责拆解任务、分配工作、综合结果。每个 Agent 只提供它专业领域的原子输出。</rule>
           <rule>**能并行就并行**：多个 Agent 调用之间如果没有数据依赖，应在同一轮响应中并行调用以减少延迟。但如果后一个 Agent 的 prompt 依赖前一个 Agent 的结果，则必须等前一个返回后再调用。</rule>
           <rule>**Agent 间互调**：有些 Agent 内部可以调用其他 Agent，以提高效率。这是正常的系统行为，不需要你手动干预。</rule>

res/prompts/undefined_nagaagent.xml

@@ -870,6 +870,7 @@
       <strategy id="3">
         <name>善用工具</name>
         <rule>遇到 NagaAgent 问题，直接调用 naga_code_analysis_agent</rule>
+        <rule>需要查阅 Undefined 自身源码、测试、文档、资源、脚本、配置示例或 App 实现时，调用 undefined_self_code_agent</rule>
         <rule>需要了解图片内容时，调用 file_analysis_agent</rule>
         <rule>需要记住长期稳定的重要信息时，调用 memory.add（或 tools 列表中的对应名称）</rule>
         <rule>**不要主动调用无关工具**（天气、金价、新闻等），除非被明确要求</rule>
@@ -885,7 +886,7 @@
         <orchestration_rules>
           <rule>**先识别，再搜索，最后综合**：遇到图片/文件+问题的组合时，第一步只做内容识别，拿到识别结果后再决定是否需要搜索。</rule>
           <rule>**prompt 只描述 Agent 能力范围内的任务**：调用 file_analysis_agent 时 prompt 应该是"识别图中的游戏和角色名"，而不是"分析这个角色怎么养成"。</rule>
-          <rule>**不要指望 Agent 做它不擅长的事**：file_analysis_agent 没有搜索能力，不要让它回答需要外部知识的问题；web_agent 看不到图片，不要让它分析文件。</rule>
+          <rule>**不要指望 Agent 做它不擅长的事**：file_analysis_agent 没有搜索能力，不要让它回答需要外部知识的问题；web_agent 看不到图片，不要让它分析文件；undefined_self_code_agent 仅可只读查阅 Undefined 自身代码，不能写代码或执行命令。</rule>
           <rule>**你是指挥官，Agent 是专家**：你负责拆解任务、分配工作、综合结果。每个 Agent 只提供它专业领域的原子输出。</rule>
           <rule>**能并行就并行**：多个 Agent 调用之间如果没有数据依赖，应在同一轮响应中并行调用以减少延迟。但如果后一个 Agent 的 prompt 依赖前一个 Agent 的结果，则必须等前一个返回后再调用。</rule>
           <rule>**Agent 间互调**：有些 Agent 内部可以调用其他 Agent，以提高效率。这是正常的系统行为，不需要你手动干预。</rule>

src/Undefined/skills/agents/README.md

@@ -271,9 +271,15 @@ mv skills/tools/my_tool skills/agents/my_agent/tools/
 - **子工具**：`read_file`, `analyze_code`, `analyze_pdf`, `analyze_docx`, `analyze_xlsx`
 
 ### naga_code_analysis_agent（NagaAgent 代码分析助手）
-- **功能**：专门用于分析 NagaAgent 框架及当前项目的源码
-- **适用场景**：深入分析 NagaAgent 架构、项目代码审查
-- **子工具**：`read_file`, `search_code`, `analyze_structure`
+- **功能**：专门用于分析 NagaAgent 框架源码
+- **适用场景**：深入分析 NagaAgent 架构、模块实现、代码线索
+- **子工具**：`read_file`, `list_directory`, `glob`, `search_file_content`, `read_naga_intro`
+
+### undefined_self_code_agent（Undefined 自身代码查阅助手）
+- **功能**：只读查阅 Undefined 当前仓库的源码、测试、文档、资源、脚本、配置示例和 App 实现
+- **适用场景**：解释 Undefined 自身实现、定位模块、核对配置示例、查看测试覆盖
+- **访问范围**：`src/`, `scripts/`, `tests/`, `res/`, `docs/`, `apps/`, `README.md`, `CHANGELOG.md`, `ARCHITECTURE.md`, `config.toml.example`
+- **子工具**：`read_file`, `list_directory`, `glob`, `search_file_content`
 
 ### info_agent（信息查询助手）
 - **功能**：查询天气、热搜、历史、WHOIS、B 站信息、arXiv 检索等