@zhin.js/agent 0.0.17 → 0.0.19

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @zhin.js/agent
 
+## 0.0.19
+
+### Patch Changes
+
+- 20ab379: fix: ai 优化
+- Updated dependencies [20ab379]
+  - @zhin.js/ai@1.0.17
+  - @zhin.js/core@1.0.56
+
+## 0.0.18
+
+### Patch Changes
+
+- 75709e1: fix: ai 强化,文档梳理
+- Updated dependencies [75709e1]
+  - @zhin.js/core@1.0.55
+  - @zhin.js/ai@1.0.16
+
 ## 0.0.17
 
 ### Patch Changes

package/README.md

@@ -7,10 +7,13 @@ Zhin AI Agent 组合层：在 `@zhin.js/core` 的类型与 Provider 之上，提
 - 🤖 **Agent 循环**：`Agent` / `createAgent`，支持工具调用、迭代与事件
 - 📝 **会话管理**：`SessionManager`、内存/数据库会话、`SessionManager.generateId`
 - 🧠 **ZhinAgent**：与 Zhin 消息流集成的智能体（SOUL/TOOLS/AGENTS、工具收集、执行策略）
+- �️ **6 层 Bash 安全**：`ExecPolicy` 纵深防御（危险黑名单、环境变量剥离、wrapper 剥离、复合命令拆分、只读放行、交互式审批）
+- 📂 **文件访问安全**：`FilePolicy` 路径检查、设备路径拦截、命令读写分类
+- 📋 **10 段系统提示词**：`PromptBuilder` 结构化 prompt（Identity、System、Tasks、Actions、Tools、Communication、Skills、Active Skills、Memory、Bootstrap）
 - 🔌 **框架挂载**：`initAgentModule()` 注册 `ctx.ai`、定时任务、DB 模型等
 - 📦 **上下文与记忆**：`ContextManager`、`ConversationMemory`、`UserProfileStore`
 - ⏰ **跟进与定时**：`FollowUpManager`、`PersistentCronEngine`、cron 工具
-- 🔧 **内置工具**：calculator、time、search、codeRunner、http、memory 等
+- 🔧 **内置工具**：bash、read_file、write_file、ask_user、web_search、chat_history 等
 - 📐 **会话压缩**：`compactSession`、token 估算、总结与裁剪
 - 🪝 **Hook 系统**：`registerAIHook`、`triggerAIHook` 等
 
@@ -76,7 +79,9 @@ const result = await agent.run('你好')
 | 初始化 | `initAgentModule` |
 | Agent | `Agent`, `createAgent`, `formatToolTitle` |
 | 服务与会话 | `AIService`, `SessionManager`, `MemorySessionManager`, `DatabaseSessionManager`, `createMemorySessionManager`, `createDatabaseSessionManager` |
-| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / tool-collector / prompt / builtin-tools 等子模块 |
+| ZhinAgent | `ZhinAgent`，以及 config / exec-policy / file-policy / tool-collector / prompt / builtin-tools 等子模块 |
+| 安全策略 | `checkExecPolicy`, `applyExecPolicyToTools`, `isDangerousCommand`, `stripEnvVarPrefix`, `stripSafeWrappers`, `splitCompoundCommand`, `extractCommandName`, `ExecPolicyResult`, `checkFileAccess`, `classifyBashCommand`, `isBlockedDevicePath` |
+| 提示词构建 | `buildRichSystemPrompt`, `buildEnhancedPersona`, `buildUserMessageWithHistory`, `buildContextHint` |
 | 上下文与记忆 | `ContextManager`, `createContextManager`, `ConversationMemory`, `UserProfileStore` |
 | 跟进与定时 | `FollowUpManager`, `PersistentCronEngine`, `createCronTools`, `setCronManager`, `getCronManager` |
 | 压缩与 Bootstrap | `compactSession`, `estimateTokens`, `loadBootstrapFiles`, `loadSoulPersona`, `loadToolsGuide`, `loadAgentsMemory` |
@@ -190,8 +195,9 @@ src/
 ├── hooks.ts
 ├── output.ts
 ├── tools.ts
-├── builtin-tools.ts
+├── builtin-tools.ts      # 内置工具（bash、read_file、ask_user 等）
 ├── tone-detector.ts
+├── file-policy.ts        # 文件访问安全（路径检查、设备拦截、命令分类）
 ├── init.ts               # initAgentModule 精简入口（委托子模块）
 ├── init/                 # init 子模块（从 init.ts 拆分）
 │   ├── shared-refs.ts
@@ -207,11 +213,11 @@ src/
 │   └── register-builtin-tools.ts
 └── zhin-agent/           # ZhinAgent 及子模块
     ├── index.ts          # ZhinAgent 主类
-    ├── config.ts
-    ├── exec-policy.ts
-    ├── tool-collector.ts
-    ├── prompt.ts
-    └── builtin-tools.ts
+    ├── config.ts         # 配置与常量（ModelSizeHint、KEYWORD_TRIGGERS 等）
+    ├── exec-policy.ts    # Bash 执行安全（6 层纵深防御）
+    ├── tool-collector.ts # 工具收集与过滤
+    ├── prompt.ts         # 系统提示词构建器（10 段结构化架构）
+    └── builtin-tools.ts  # ZhinAgent 专用内置工具
 ```
 
 ### 构建

package/lib/builtin-tools.d.ts

@@ -1,30 +1,21 @@
 /**
  * AI 内置系统工具
  *
- * 借鉴 OpenClaw/MicroClaw 的实用工具设计，为 ZhinAgent 提供：
- *
  * 文件工具:  read_file, write_file, edit_file, list_dir, glob, grep
  * Shell:     bash
  * 网络:      web_search, web_fetch
  * 计划:      todo_read, todo_write
  * 记忆:      read_memory, write_memory (AGENTS.md)
  * 技能:      activate_skill, install_skill
- * 会话:      session_status, compact_session
- * 技能发现:  工作区 skills/ 目录自动扫描
- * 引导文件:  SOUL.md, TOOLS.md, AGENTS.md 自动加载
+ * 交互:      ask_user（基于 Prompt 类的用户确认/提问工具）
+ *
+ * 发现逻辑已拆分到 discover-skills.ts / discover-agents.ts / discover-tools.ts
  */
 import { type Plugin } from '@zhin.js/core';
 import { ZhinTool } from '@zhin.js/core';
-export { loadSoulPersona, loadToolsGuide, loadAgentsMemory } from './bootstrap.js';
-/**
- * 从根插件树收集：根插件与**直接子插件**包目录下的 `skills/`（其下为 `<name>/SKILL.md`）
- */
-export declare function collectPluginSkillSearchRoots(root: Plugin | null | undefined): string[];
-/**
- * 技能发现与 activate_skill 查找共用：标准目录 + 已加载插件包 skills/
- */
-export declare function getSkillSearchDirectories(root?: Plugin | null): string[];
 export interface BuiltinToolsOptions {
+    /** 插件实例，用于 ask_user 工具创建 Prompt 交互 */
+    plugin?: Plugin;
     /** Max chars for skill instruction extraction (model-size-aware) */
     skillInstructionMaxChars?: number;
     /**
@@ -41,127 +32,4 @@ export interface BuiltinToolsOptions {
  * 创建所有内置系统工具
  */
 export declare function createBuiltinTools(options?: BuiltinToolsOptions): ZhinTool[];
-export interface SkillMeta {
-    name: string;
-    description: string;
-    keywords?: string[];
-    tags?: string[];
-    /** SKILL.md frontmatter 中声明的关联工具名列表 */
-    toolNames?: string[];
-    filePath: string;
-    /** 是否常驻注入 system prompt（frontmatter always: true） */
-    always?: boolean;
-    /** 当前环境是否满足依赖（bins/env） */
-    available?: boolean;
-    /** 缺失的依赖描述（如 "CLI: ffmpeg", "ENV: API_KEY"） */
-    requiresMissing?: string[];
-}
-/**
- * 扫描技能目录，发现 SKILL.md 技能文件
- * 加载顺序：Workspace（cwd/skills）> Local（~/.zhin/skills）> data/skills > 已加载插件包 skills/，同名先发现者优先
- * 支持平台/依赖兼容性过滤。内置技能由 create-zhin 在创建项目时写入 skills/summarize 等。
- *
- * @param root 根插件（可选）：用于追加插件包内 `skills/` 扫描，与 `activate_skill` 查找路径一致
- */
-export declare function discoverWorkspaceSkills(root?: Plugin | null): Promise<SkillMeta[]>;
-/**
- * 获取 frontmatter 中 always: true 的技能名列表（用于常驻注入 system prompt）
- */
-export declare function getAlwaysSkillNames(skills: SkillMeta[]): string[];
-/**
- * 加载 always 技能的正文内容并拼接为「Active Skills」段
- */
-export declare function loadAlwaysSkillsContent(skills: SkillMeta[]): Promise<string>;
-/**
- * 构建技能列表的 XML 摘要，供 model 区分可用/不可用及缺失依赖
- */
-export declare function buildSkillsSummaryXML(skills: SkillMeta[]): string;
-/**
- * Agent 预设元数据（从 *.agent.md frontmatter 解析）
- */
-export interface AgentMeta {
-    name: string;
-    description: string;
-    keywords?: string[];
-    tags?: string[];
-    /** frontmatter 中声明的工具名列表 */
-    toolNames?: string[];
-    /** *.agent.md 文件的绝对路径 */
-    filePath: string;
-    /** 首选模型名 */
-    model?: string;
-    /** 首选 Provider 名 */
-    provider?: string;
-    /** 最大工具调用迭代次数 */
-    maxIterations?: number;
-}
-/**
- * 扫描 agents/ 目录，发现 *.agent.md 文件
- * 加载顺序与 skills 一致：Workspace > ~/.zhin > data > 插件包
- * 同名先发现者优先
- */
-export declare function discoverWorkspaceAgents(root?: Plugin | null): Promise<AgentMeta[]>;
-/**
- * 简写参数定义（*.tool.md frontmatter 中使用）
- */
-export interface ToolParamShorthand {
-    type: string;
-    description?: string;
-    required?: boolean;
-    enum?: string[];
-    default?: any;
-}
-/**
- * Tool 元数据（从 *.tool.md frontmatter 解析）
- */
-export interface ToolMeta {
-    name: string;
-    description: string;
-    /** 简写参数定义（frontmatter 格式） */
-    parameters?: Record<string, ToolParamShorthand>;
-    /** 命令配置 */
-    command?: {
-        pattern?: string;
-        alias?: string[];
-        examples?: string[];
-    };
-    /** 支持的平台列表 */
-    platforms?: string[];
-    /** 支持的场景列表 */
-    scopes?: string[];
-    /** 权限级别 */
-    permissionLevel?: string;
-    /** 标签 */
-    tags?: string[];
-    /** 触发关键词 */
-    keywords?: string[];
-    /** 工具分类 */
-    kind?: string;
-    /** 是否隐藏 */
-    hidden?: boolean;
-    /** handler 文件路径（相对于 .tool.md） */
-    handler?: string;
-    /** *.tool.md 文件的绝对路径 */
-    filePath: string;
-    /** body 内容（无 handler 时作为 prompt 模板） */
-    templateBody?: string;
-}
-/**
- * 从根插件树收集：根插件与直接子插件包目录下的 `tools/`
- */
-export declare function collectPluginToolSearchRoots(root: Plugin | null | undefined): string[];
-/**
- * 获取所有 tool 搜索目录（标准目录 + 插件包 tools/）
- */
-export declare function getToolSearchDirectories(root?: Plugin | null): string[];
-/**
- * 扫描 tools/ 目录，发现 *.tool.md 文件
- * 加载顺序与 skills/agents 一致：Workspace > ~/.zhin > data > 插件包
- * 同名先发现者优先
- */
-export declare function discoverWorkspaceTools(root?: Plugin | null): Promise<ToolMeta[]>;
-/**
- * 将 ToolMeta 转换为 Tool 对象（包含 execute 函数）
- */
-export declare function buildToolFromMeta(meta: ToolMeta): Promise<import('@zhin.js/core').Tool | null>;
 //# sourceMappingURL=builtin-tools.d.ts.map

package/lib/builtin-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../src/builtin-tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"builtin-tools.d.ts","sourceRoot":"","sources":["../src/builtin-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EAAkB,KAAK,MAAM,EAAuB,MAAM,eAAe,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA4HzC,MAAM,WAAW,mBAAmB;IAClC,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;OAEG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,EAAE,CAAC;IAC1C;;;OAGG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;CACxD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,QAAQ,EAAE,CAirB5E"}