人工智能AI 技能MCP 服务AI 评测【免费下载链接】OpenSpaceOpenSpace: The Skill Management Layer for AI Agents -- https://open-space.cloud/项目地址https://gitcode.com/gh_mirrors/opens/OpenSpace点击查看免费下载本篇文章完整解析 OpenSpace 技能库中的dir-verify-parallel-shell-audit技能它是一套系统化的目录结构验证 并行文件审计方法论核心是在同一轮迭代中把list_dir目录枚举与run_shell复合属性检查head -N与wc -l协同调度再配合并行批量文件读取与 TypeScript 导入校验把数十个文件的审计从 NK 轮迭代压缩到 1⌈N/B⌉ 轮。读完本文你将掌握这套可复制的迭代压缩审计流程、可直接粘贴的复合 Shell 命令模板以及它在 OpenSpace 底层工具实现上的运行原理。技能定位从 SKILL.md 到可执行方法论dir-verify-parallel-shell-audit是 OpenSpace 在 My Daily Monitor 示例项目演化过程中沉淀出的技能之一其完整定义位于 examples/my-daily-monitor/skills/dir-verify-parallel-shell-audit/SKILL.md。它的官方描述是Diagnose and resolve file access issues by verifying directory structure, reading multiple files in parallel batches, running combined shell property checks (head/wc-l) in the same iteration as directory listing, and validating TypeScript import patterns — all with built-in guidance to minimize total iteration count.翻译过来这是一套面向文件访问故障诊断与源码树审计的四阶段流程目录验证与 Shell 属性检查合并执行、并行批量读取文件、TypeScript 导入模式校验、最终验证与报告。它的进化脉络清晰可循技能库中还保留着它的前身 verify-directory-structure-parallel-audit/SKILL.md只有目录验证 并行批量读取 导入校验三块以及为它提供原子检查单元的 combined-head-linecount-check/SKILL.md。本技能正是在前者的基础上把head -N/wc -l属性检查内联进 Phase 1砍掉了后来为获取文件有多少行CSS 文件首行是什么而额外付出的一整轮迭代。从 OpenSpace 项目整体看这类 SKILL.md 由 openspace/skill_engine 的技能演化引擎捕获、评估与沉淀随后在 openspace/skills 中统一注册供 Agent 在后续任务中按语义检索复用。理解这一点就能明白本技能不仅是操作手册更是 OpenSpace 中可演进、可复用、可检索技能资产的一个典型样本。核心思想为什么一次工具调用如此昂贵整个技能的一切优化都围绕一个前提在 Agent 的工作循环里一次工具调用就是一次往返round-trip占用一次模型推理迭代与上下文窗口。串行地读一个文件 → 等结果 → 读下一个文件会让几十个文件的审计膨胀为几十轮迭代而目录枚举 → 等 → 单独查行数 → 等 → 读文件 → 等则会在一开始就浪费多轮。本技能给出的解药是迭代压缩iteration collapse横向压缩把互不依赖的调用list_dir与run_shell放进同一轮并行发出纵向压缩把多个属性检查用链进同一条run_shell复合命令批量压缩把 N 个文件的读取折叠为 ⌈N/batch_size⌉ 轮。这套假设在 OpenSpace 源码中站得住脚。run_shell的底层是 Shell 后端会话在 openspace/grounding/backends/shell/transport/local_connector.py 中LocalShellConnector.run_bash_command会把脚本写入临时文件经安全策略检查SecurityPolicyManager.check_command_allowed后交给/bin/bash执行默认超时 90 秒——这意味着一条复合命令内部可以安全地串起多条子命令一次往返拿到全部输出。而list_dir、read_file等工具均声明了_is_concurrency_safe True见 openspace/grounding/backends/shell/search_tools.py 与 openspace/grounding/backends/shell/file_tools.py它们可以无副作用地并行执行这正是同轮并行设计合法性的源码依据。Phase 1 — 目录验证 Shell 属性检查合并执行关键优化在同一轮迭代中同时发起list_dir与run_shell属性检查避免后续为回答这个文件有多少行这个 CSS 文件首行是什么而额外付出专门的一轮迭代。1.1 识别目标路径收集操作涉及的每一个文件或目录路径优先使用绝对路径消除工作目录歧义。同时在这一步就标注出你已知必然需要其属性行数、头部内容的文件——通常是 CSS、配置文件或数据文件。绝对路径建议同样来自 OpenSpace 工具层的约束WriteFileTool的参数说明明确要求file_path must be absolute, not relative见 file_tools.py而 Grep/ListDir 等搜索类工具也把_get_cwd解析出的工作目录作为路径基准search_tools.py绝对路径能彻底规避两套基准混用导致的搜的是 A 目录、读的是 B 目录类错误。1.2 同一轮并行发起list_dirrun_shell对每个相关目录调用list_dir在同一轮迭代中用一条复合 Shell 命令为已知目标文件打包head与wc -l检查Iteration 1 (parallel): list_dir(src/components) list_dir(src/styles) run_shell(head -5 src/styles/main.css echo --- wc -l src/styles/main.css) run_shell(head -3 vite.config.ts echo --- wc -l src/main.ts)复合 Shell 模式把 head wc 其他检查合并到一条命令# 单次 run_shell 调用——多文件、多检查、零额外迭代 head -10 path/to/file.css echo LINE_COUNT: wc -l path/to/file.css \ echo --- head -5 path/to/config.ts echo LINE_COUNT: wc -l path/to/config.ts关于list_dir能拿到什么源码给出了确切答案ListDirTool是直接基于os.scandir实现的并不 shell outsearch_tools.py每条输出形如-rw-r--r-- 1234 2026-10-08 19:39 src/main.ts——包含权限模式stat.filemode、文件大小st_size、修改时间st_mtime目录名带/后缀符号链接显示- 目标。也就是说list_dir本身就顺带完成了权限模式文件大小两类属性的采集你在 Phase 1 需要补的只剩内容型属性头部、行数。1.3 验证存在性与权限确认目录存在且当前用户具备读必要时还有写/执行权限。目录缺失则先用mkdir -p创建再继续权限不足则调整后再重试。这一步对应技能清单中的两个常见修复项Directory missing → create with mkdir -p与Permissions insufficient → chmod/chown or escalate。从源码看工具层在check_permissions阶段会走check_read_permission_for_tool/check_write_permission_for_tool的权限级联如ReadFileTool.check_permissionsfile_tools.py因此文件读不到既可能是路径错也可能是权限策略拦截——两者都要在验证阶段区分。1.4 构建文件清单Manifest从list_dir输出汇总待审计文件的完整清单按子目录或文件类型分组为 Phase 2 的并行批量读取做准备。清单既是读取计划的输入也是 Phase 3 校验 barrel 导出、Phase 4 生成报告的对账基准。1.5 记录 Shell 检查结果解析并保存head/wc -l输出与清单并置。由于这些数据已在 Phase 1 零额外迭代地取回最终审计报告无需再补任何一轮。Phase 2 — 并行批量文件读取为什么重要串行读取一个文件消耗一轮迭代并行批量读取把 N 个文件折叠为 ⌈N/batch_size⌉ 轮——审计几十个文件时这是数量级的加速。2.1 确定批量大小默认每批5–10 个文件。单个文件很大时减小批量小配置文件 / index 文件可以加大。Phase 1 中已用head预览过部分内容的文件若需要完整内容在这里仍应完整读取——head只负责探头部不替代读全文。2.2 同批并行发起read_file批次内所有read_file在同一轮发出不等待上一个完成再请求下一个Batch 1 (parallel): read_file(src/components/A.tsx) read_file(src/components/B.tsx) read_file(src/components/C.tsx) read_file(src/components/D.tsx) read_file(src/components/E.tsx) Batch 2 (parallel): read_file(src/components/F.tsx) ...read_file的参数语义可以对照ReadFileTool的实现确认file_path必填offset1 起始行号默认 1与limit行数上限用于超大文件分段读取file_tools.py。这也解释了技能的隐含约束——大文件应主动用 offset/limit 分段而不是让单次读取淹没上下文窗口。2.3 收集与分类结果每批返回后立刻扫描错误file-not-found、permission denied并标记不要因单个失败而中止剩余批次继续聚合全部发现。这呼应了 OpenSpace 工具层的容错设计ReadFileTool对不存在路径会返回带Path does not exist与 cwd 提示的 ToolResult可对照 search_tools.py 中 GrepTool 的同类路径建议逻辑错误本身即诊断信息值得全量收集。2.4 重新验证缺失文件对报缺失的文件先对其父目录重新list_dir确认是文件真不存在还是路径写错必要时修正路径后单独重试该文件。这正是技能清单中Path typo → re-enumerate with list_dir, correct path的执行步骤。Phase 3 — TypeScript 导入验证本阶段针对审计 TypeScript 源码树时最常见的一类结构性缺陷。3.1 提取导入语句对 Phase 2 读过的每个.ts/.tsx文件抽出所有import行。3.2 分类导入类型——Value vs. Type模式正确用途import Foo from ...运行时值类、函数、对象import { Foo } from ...运行时值导出import type Foo from ...仅类型导入编译期擦除import type { Foo } from ...仅类型的命名导入import { type Foo } from ...内联类型修饰符TS 4.53.3 标记仅作类型使用的值导入若某个未带type导入的标识符只出现在类型位置: Foo、as Foo、implements Foo、泛型参数应改写为import type。这能杜绝意外的运行时依赖并满足verbatimModuleSyntax/isolatedModules编译选项// ❌ 修改前——值导入仅用作类型 import { UserProfile } from ./types; const handler (u: UserProfile) { ... }; // ✅ 修改后——仅类型导入 import type { UserProfile } from ./types; const handler (u: UserProfile) { ... };这条建议在示例项目中不是空谈My Daily Monitor 的 examples/my-daily-monitor/tsconfig.json 明确开启了isolatedModules: true。在该开关下每个文件会被独立转译典型场景是 Vite/esbuild 的按文件转译运行时值导入与类型导入混用容易造成导入但从未作为值使用的冗余依赖甚至转译差异——import type是零运行时成本的正确姿势。3.4 标记重复导入检测同一模块在文件内被多次导入常来自复制粘贴合并为单条// ❌ 重复 import { A } from ./utils; import { B } from ./utils; // ✅ 合并 import { A, B } from ./utils;3.5 验证 Barrel / Index 导出当目录含index.tsbarrel 文件时确认每个应公开的组件或模块都被重新导出并与 Phase 1 的文件清单交叉比对。技能把它表述为一句金律barrel 文件是契约——即便底层文件正确缺失导出也是 bug。3.6 应用修复并重新审计对每个文件以单次写操作应用全部导入修正写完后并行批量重读受影响文件确认修复生效。这里的单次写操作与 OpenSpace 工具层的约束天然契合WriteFileTool会校验目标文件必须已被读过通过ToolUseContext.read_file_state追踪并检查 mtime 防止并发改写file_tools.py——所以先批量读完、再批量写、最后批量重读的节奏正好满足它的前置校验。Phase 4 — 最终验证与报告重试原始操作目录结构确认、导入问题解决后重试最初失败的操作。输出审计报告覆盖枚举与读取的文件总数使用的批次数量突出相对串行的迭代节省量Phase 1 以零额外迭代收集的 Shell 属性检查结果行数、文件头部发现并修复的导入问题值→类型转换、重复合并、缺失 barrel 导出剩余未决问题与建议的下一步。报告是闭环的关键它既是本轮审计的交付物也是后续同类问题的离线调试日志素材对应最佳实践中Log intermediate findings。快速参考迭代压缩模式# 串行慢—— N 个文件 K 次属性检查 NK 轮迭代 list_dir(dir) → wait run_shell(wc -l ...) → wait ← 本可消除的额外迭代 read_file(file1) → wait read_file(file2) → wait ... # 优化快—— 1 ⌈N/B⌉ 轮迭代 [list_dir(dir), run_shell(head -5 f1 wc -l f1 head -5 f2 wc -l f2)] ← 1 轮Phase 1 [read_file(file1), read_file(file2), ..., read_file(fileB)] ← 1 轮Phase 2批次 1 [read_file(fileB1), ...] ← 1 轮Phase 2批次 2复合 Shell 命令模板# 检查单个文件的头部 行数 head -10 /path/to/file.css echo LINES: wc -l /path/to/file.css # 一条 run_shell 检查多个文件 head -5 /path/to/a.css echo LINES_A: wc -l /path/to/a.css \ echo \ head -5 /path/to/b.ts echo LINES_B: wc -l /path/to/b.ts # 验证文件以期望内容开头如 CSS 主题注释 head -1 /path/to/styles.css | grep -q Theme Colors echo OK || echo MISSING HEADER # 统计目录中匹配模式的文件数 ls src/components/*.tsx | wc -l这套模板与combined-head-linecount-check技能的原子模式head -N file echo --- wc -l file见 combined-head-linecount-check/SKILL.md一脉相承echo分隔符让输出可读性极佳——分隔线上方是内容下方是行数。而wc -l file的输入重定向写法只输出数字、不夹带文件名在echo已标明文件身份的复合命令里输出更干净。最佳实践Shell 检查与list_dir协同调度任何你预知需要的wc -l或head -N都要与最初的list_dir放在同一轮绝不放进后续专门的一轮。把多个 Shell 检查捆绑进一条run_shell用或;把多个文件的 head/wc/grep 串成一次run_shell调用。每次run_shell占用一个工具槽位捆绑即省槽位。先枚举、再读取先list_dir后批量读永远不要猜文件名。全程使用绝对路径规避工作目录歧义。按局部性分批同一目录的文件放进同一批保持上下文连贯。类型导入运行时零成本任何仅作 TypeScript 类型使用的符号优先import type尤其isolatedModules: true的项目。Barrel 文件是契约index.ts导出即模块公共 API缺失导出即使底层文件正确也是 bug。记录中间发现Phase 3 后问题仍存在时导出完整审计日志供离线排查。常见修复类别清单目录缺失 → 用mkdir -p创建权限不足 →chmod/chown或升级权限路径拼写错误 → 用list_dir重新枚举、修正路径文件行数不符 → 用wc -l检查Phase 1 已零成本采集文件头部内容不符 → 用head -N检查Phase 1 已零成本采集值导入被当类型使用 → 添加import type重复导入 → 合并为单条语句缺失 barrel 导出 → 向index.ts添加再导出循环导入 → 重构模块边界在真实仓库中的一次完整演练示意这套技能在 My Daily Monitor 这样的中型 TS 项目里场景感极强它有 29 个组件、14 个服务与多层配置examples/my-daily-monitor/README.md 的项目结构一节一旦出现面板加载失败import 报错这类问题恰好触发本技能的四阶段流程。技能库中还沉淀了与之配套的同类可靠性技能如typescript-import-audit、typescript-typecheck-fallback、verify-directory-structure-parallel-audit见 examples/my-daily-monitor/skills 目录它们与本技能相互印证先并行摸清目录与文件属性再批量读全量内容最后按编译约束修正导入是 OpenSpace 在与真实代码库长期交互中反复验证过的可靠审计路径。赞分享人工智能AI 技能MCP 服务AI 评测【免费下载链接】OpenSpaceOpenSpace: The Skill Management Layer for AI Agents -- https://open-space.cloud/项目地址https://gitcode.com/gh_mirrors/opens/OpenSpace点击查看免费下载相关推荐OpenSpace Agent 技能实战用 head wc -l 合并调用实现最小化 Shell 往返开销OpenSpace Agent 技能实战用 head wc l 合并调用实现最小化 Shell 往返开销 导读 本文围绕 OpenSpace 技能库中的人工智能AI 技能MCP 服务AI 评测OpenSpace Agent 技能实战用 run_shell Python Heredoc 构建可靠代码执行回退shell-python-fallbackOpenSpace Agent 技能实战用 run_shell Python Heredoc 构建可靠代码执行回退shell python fallba人工智能AI 技能MCP 服务AI 评测在 Clojure 中为 shell 命令指定执行目录clojure.java.shell 的 with-sh-dir 与 :dir 用法在 Clojure 中为 shell 命令指定执行目录clojure.java.shell 的 with sh dir 与 :dir 用法 Clojure 通文档教程知识库上一篇Video2X让AI重新定义视频画质与流畅度的革命性工具下一篇WechatBakTool微信聊天记录备份工具数据安全保护的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenSpace 技能实战：dir-verify-parallel-shell-audit —— 用并行 Shell 属性检查实现目录审计的迭代压缩
人工智能AI 技能MCP 服务AI 评测【免费下载链接】OpenSpaceOpenSpace: The Skill Management Layer for AI Agents -- https://open-space.cloud/项目地址https://gitcode.com/gh_mirrors/opens/OpenSpace点击查看免费下载本篇文章完整解析 OpenSpace 技能库中的dir-verify-parallel-shell-audit技能它是一套系统化的目录结构验证 并行文件审计方法论核心是在同一轮迭代中把list_dir目录枚举与run_shell复合属性检查head -N与wc -l协同调度再配合并行批量文件读取与 TypeScript 导入校验把数十个文件的审计从 NK 轮迭代压缩到 1⌈N/B⌉ 轮。读完本文你将掌握这套可复制的迭代压缩审计流程、可直接粘贴的复合 Shell 命令模板以及它在 OpenSpace 底层工具实现上的运行原理。技能定位从 SKILL.md 到可执行方法论dir-verify-parallel-shell-audit是 OpenSpace 在 My Daily Monitor 示例项目演化过程中沉淀出的技能之一其完整定义位于 examples/my-daily-monitor/skills/dir-verify-parallel-shell-audit/SKILL.md。它的官方描述是Diagnose and resolve file access issues by verifying directory structure, reading multiple files in parallel batches, running combined shell property checks (head/wc-l) in the same iteration as directory listing, and validating TypeScript import patterns — all with built-in guidance to minimize total iteration count.翻译过来这是一套面向文件访问故障诊断与源码树审计的四阶段流程目录验证与 Shell 属性检查合并执行、并行批量读取文件、TypeScript 导入模式校验、最终验证与报告。它的进化脉络清晰可循技能库中还保留着它的前身 verify-directory-structure-parallel-audit/SKILL.md只有目录验证 并行批量读取 导入校验三块以及为它提供原子检查单元的 combined-head-linecount-check/SKILL.md。本技能正是在前者的基础上把head -N/wc -l属性检查内联进 Phase 1砍掉了后来为获取文件有多少行CSS 文件首行是什么而额外付出的一整轮迭代。从 OpenSpace 项目整体看这类 SKILL.md 由 openspace/skill_engine 的技能演化引擎捕获、评估与沉淀随后在 openspace/skills 中统一注册供 Agent 在后续任务中按语义检索复用。理解这一点就能明白本技能不仅是操作手册更是 OpenSpace 中可演进、可复用、可检索技能资产的一个典型样本。核心思想为什么一次工具调用如此昂贵整个技能的一切优化都围绕一个前提在 Agent 的工作循环里一次工具调用就是一次往返round-trip占用一次模型推理迭代与上下文窗口。串行地读一个文件 → 等结果 → 读下一个文件会让几十个文件的审计膨胀为几十轮迭代而目录枚举 → 等 → 单独查行数 → 等 → 读文件 → 等则会在一开始就浪费多轮。本技能给出的解药是迭代压缩iteration collapse横向压缩把互不依赖的调用list_dir与run_shell放进同一轮并行发出纵向压缩把多个属性检查用链进同一条run_shell复合命令批量压缩把 N 个文件的读取折叠为 ⌈N/batch_size⌉ 轮。这套假设在 OpenSpace 源码中站得住脚。run_shell的底层是 Shell 后端会话在 openspace/grounding/backends/shell/transport/local_connector.py 中LocalShellConnector.run_bash_command会把脚本写入临时文件经安全策略检查SecurityPolicyManager.check_command_allowed后交给/bin/bash执行默认超时 90 秒——这意味着一条复合命令内部可以安全地串起多条子命令一次往返拿到全部输出。而list_dir、read_file等工具均声明了_is_concurrency_safe True见 openspace/grounding/backends/shell/search_tools.py 与 openspace/grounding/backends/shell/file_tools.py它们可以无副作用地并行执行这正是同轮并行设计合法性的源码依据。Phase 1 — 目录验证 Shell 属性检查合并执行关键优化在同一轮迭代中同时发起list_dir与run_shell属性检查避免后续为回答这个文件有多少行这个 CSS 文件首行是什么而额外付出专门的一轮迭代。1.1 识别目标路径收集操作涉及的每一个文件或目录路径优先使用绝对路径消除工作目录歧义。同时在这一步就标注出你已知必然需要其属性行数、头部内容的文件——通常是 CSS、配置文件或数据文件。绝对路径建议同样来自 OpenSpace 工具层的约束WriteFileTool的参数说明明确要求file_path must be absolute, not relative见 file_tools.py而 Grep/ListDir 等搜索类工具也把_get_cwd解析出的工作目录作为路径基准search_tools.py绝对路径能彻底规避两套基准混用导致的搜的是 A 目录、读的是 B 目录类错误。1.2 同一轮并行发起list_dirrun_shell对每个相关目录调用list_dir在同一轮迭代中用一条复合 Shell 命令为已知目标文件打包head与wc -l检查Iteration 1 (parallel): list_dir(src/components) list_dir(src/styles) run_shell(head -5 src/styles/main.css echo --- wc -l src/styles/main.css) run_shell(head -3 vite.config.ts echo --- wc -l src/main.ts)复合 Shell 模式把 head wc 其他检查合并到一条命令# 单次 run_shell 调用——多文件、多检查、零额外迭代 head -10 path/to/file.css echo LINE_COUNT: wc -l path/to/file.css \ echo --- head -5 path/to/config.ts echo LINE_COUNT: wc -l path/to/config.ts关于list_dir能拿到什么源码给出了确切答案ListDirTool是直接基于os.scandir实现的并不 shell outsearch_tools.py每条输出形如-rw-r--r-- 1234 2026-10-08 19:39 src/main.ts——包含权限模式stat.filemode、文件大小st_size、修改时间st_mtime目录名带/后缀符号链接显示- 目标。也就是说list_dir本身就顺带完成了权限模式文件大小两类属性的采集你在 Phase 1 需要补的只剩内容型属性头部、行数。1.3 验证存在性与权限确认目录存在且当前用户具备读必要时还有写/执行权限。目录缺失则先用mkdir -p创建再继续权限不足则调整后再重试。这一步对应技能清单中的两个常见修复项Directory missing → create with mkdir -p与Permissions insufficient → chmod/chown or escalate。从源码看工具层在check_permissions阶段会走check_read_permission_for_tool/check_write_permission_for_tool的权限级联如ReadFileTool.check_permissionsfile_tools.py因此文件读不到既可能是路径错也可能是权限策略拦截——两者都要在验证阶段区分。1.4 构建文件清单Manifest从list_dir输出汇总待审计文件的完整清单按子目录或文件类型分组为 Phase 2 的并行批量读取做准备。清单既是读取计划的输入也是 Phase 3 校验 barrel 导出、Phase 4 生成报告的对账基准。1.5 记录 Shell 检查结果解析并保存head/wc -l输出与清单并置。由于这些数据已在 Phase 1 零额外迭代地取回最终审计报告无需再补任何一轮。Phase 2 — 并行批量文件读取为什么重要串行读取一个文件消耗一轮迭代并行批量读取把 N 个文件折叠为 ⌈N/batch_size⌉ 轮——审计几十个文件时这是数量级的加速。2.1 确定批量大小默认每批5–10 个文件。单个文件很大时减小批量小配置文件 / index 文件可以加大。Phase 1 中已用head预览过部分内容的文件若需要完整内容在这里仍应完整读取——head只负责探头部不替代读全文。2.2 同批并行发起read_file批次内所有read_file在同一轮发出不等待上一个完成再请求下一个Batch 1 (parallel): read_file(src/components/A.tsx) read_file(src/components/B.tsx) read_file(src/components/C.tsx) read_file(src/components/D.tsx) read_file(src/components/E.tsx) Batch 2 (parallel): read_file(src/components/F.tsx) ...read_file的参数语义可以对照ReadFileTool的实现确认file_path必填offset1 起始行号默认 1与limit行数上限用于超大文件分段读取file_tools.py。这也解释了技能的隐含约束——大文件应主动用 offset/limit 分段而不是让单次读取淹没上下文窗口。2.3 收集与分类结果每批返回后立刻扫描错误file-not-found、permission denied并标记不要因单个失败而中止剩余批次继续聚合全部发现。这呼应了 OpenSpace 工具层的容错设计ReadFileTool对不存在路径会返回带Path does not exist与 cwd 提示的 ToolResult可对照 search_tools.py 中 GrepTool 的同类路径建议逻辑错误本身即诊断信息值得全量收集。2.4 重新验证缺失文件对报缺失的文件先对其父目录重新list_dir确认是文件真不存在还是路径写错必要时修正路径后单独重试该文件。这正是技能清单中Path typo → re-enumerate with list_dir, correct path的执行步骤。Phase 3 — TypeScript 导入验证本阶段针对审计 TypeScript 源码树时最常见的一类结构性缺陷。3.1 提取导入语句对 Phase 2 读过的每个.ts/.tsx文件抽出所有import行。3.2 分类导入类型——Value vs. Type模式正确用途import Foo from ...运行时值类、函数、对象import { Foo } from ...运行时值导出import type Foo from ...仅类型导入编译期擦除import type { Foo } from ...仅类型的命名导入import { type Foo } from ...内联类型修饰符TS 4.53.3 标记仅作类型使用的值导入若某个未带type导入的标识符只出现在类型位置: Foo、as Foo、implements Foo、泛型参数应改写为import type。这能杜绝意外的运行时依赖并满足verbatimModuleSyntax/isolatedModules编译选项// ❌ 修改前——值导入仅用作类型 import { UserProfile } from ./types; const handler (u: UserProfile) { ... }; // ✅ 修改后——仅类型导入 import type { UserProfile } from ./types; const handler (u: UserProfile) { ... };这条建议在示例项目中不是空谈My Daily Monitor 的 examples/my-daily-monitor/tsconfig.json 明确开启了isolatedModules: true。在该开关下每个文件会被独立转译典型场景是 Vite/esbuild 的按文件转译运行时值导入与类型导入混用容易造成导入但从未作为值使用的冗余依赖甚至转译差异——import type是零运行时成本的正确姿势。3.4 标记重复导入检测同一模块在文件内被多次导入常来自复制粘贴合并为单条// ❌ 重复 import { A } from ./utils; import { B } from ./utils; // ✅ 合并 import { A, B } from ./utils;3.5 验证 Barrel / Index 导出当目录含index.tsbarrel 文件时确认每个应公开的组件或模块都被重新导出并与 Phase 1 的文件清单交叉比对。技能把它表述为一句金律barrel 文件是契约——即便底层文件正确缺失导出也是 bug。3.6 应用修复并重新审计对每个文件以单次写操作应用全部导入修正写完后并行批量重读受影响文件确认修复生效。这里的单次写操作与 OpenSpace 工具层的约束天然契合WriteFileTool会校验目标文件必须已被读过通过ToolUseContext.read_file_state追踪并检查 mtime 防止并发改写file_tools.py——所以先批量读完、再批量写、最后批量重读的节奏正好满足它的前置校验。Phase 4 — 最终验证与报告重试原始操作目录结构确认、导入问题解决后重试最初失败的操作。输出审计报告覆盖枚举与读取的文件总数使用的批次数量突出相对串行的迭代节省量Phase 1 以零额外迭代收集的 Shell 属性检查结果行数、文件头部发现并修复的导入问题值→类型转换、重复合并、缺失 barrel 导出剩余未决问题与建议的下一步。报告是闭环的关键它既是本轮审计的交付物也是后续同类问题的离线调试日志素材对应最佳实践中Log intermediate findings。快速参考迭代压缩模式# 串行慢—— N 个文件 K 次属性检查 NK 轮迭代 list_dir(dir) → wait run_shell(wc -l ...) → wait ← 本可消除的额外迭代 read_file(file1) → wait read_file(file2) → wait ... # 优化快—— 1 ⌈N/B⌉ 轮迭代 [list_dir(dir), run_shell(head -5 f1 wc -l f1 head -5 f2 wc -l f2)] ← 1 轮Phase 1 [read_file(file1), read_file(file2), ..., read_file(fileB)] ← 1 轮Phase 2批次 1 [read_file(fileB1), ...] ← 1 轮Phase 2批次 2复合 Shell 命令模板# 检查单个文件的头部 行数 head -10 /path/to/file.css echo LINES: wc -l /path/to/file.css # 一条 run_shell 检查多个文件 head -5 /path/to/a.css echo LINES_A: wc -l /path/to/a.css \ echo \ head -5 /path/to/b.ts echo LINES_B: wc -l /path/to/b.ts # 验证文件以期望内容开头如 CSS 主题注释 head -1 /path/to/styles.css | grep -q Theme Colors echo OK || echo MISSING HEADER # 统计目录中匹配模式的文件数 ls src/components/*.tsx | wc -l这套模板与combined-head-linecount-check技能的原子模式head -N file echo --- wc -l file见 combined-head-linecount-check/SKILL.md一脉相承echo分隔符让输出可读性极佳——分隔线上方是内容下方是行数。而wc -l file的输入重定向写法只输出数字、不夹带文件名在echo已标明文件身份的复合命令里输出更干净。最佳实践Shell 检查与list_dir协同调度任何你预知需要的wc -l或head -N都要与最初的list_dir放在同一轮绝不放进后续专门的一轮。把多个 Shell 检查捆绑进一条run_shell用或;把多个文件的 head/wc/grep 串成一次run_shell调用。每次run_shell占用一个工具槽位捆绑即省槽位。先枚举、再读取先list_dir后批量读永远不要猜文件名。全程使用绝对路径规避工作目录歧义。按局部性分批同一目录的文件放进同一批保持上下文连贯。类型导入运行时零成本任何仅作 TypeScript 类型使用的符号优先import type尤其isolatedModules: true的项目。Barrel 文件是契约index.ts导出即模块公共 API缺失导出即使底层文件正确也是 bug。记录中间发现Phase 3 后问题仍存在时导出完整审计日志供离线排查。常见修复类别清单目录缺失 → 用mkdir -p创建权限不足 →chmod/chown或升级权限路径拼写错误 → 用list_dir重新枚举、修正路径文件行数不符 → 用wc -l检查Phase 1 已零成本采集文件头部内容不符 → 用head -N检查Phase 1 已零成本采集值导入被当类型使用 → 添加import type重复导入 → 合并为单条语句缺失 barrel 导出 → 向index.ts添加再导出循环导入 → 重构模块边界在真实仓库中的一次完整演练示意这套技能在 My Daily Monitor 这样的中型 TS 项目里场景感极强它有 29 个组件、14 个服务与多层配置examples/my-daily-monitor/README.md 的项目结构一节一旦出现面板加载失败import 报错这类问题恰好触发本技能的四阶段流程。技能库中还沉淀了与之配套的同类可靠性技能如typescript-import-audit、typescript-typecheck-fallback、verify-directory-structure-parallel-audit见 examples/my-daily-monitor/skills 目录它们与本技能相互印证先并行摸清目录与文件属性再批量读全量内容最后按编译约束修正导入是 OpenSpace 在与真实代码库长期交互中反复验证过的可靠审计路径。赞分享人工智能AI 技能MCP 服务AI 评测【免费下载链接】OpenSpaceOpenSpace: The Skill Management Layer for AI Agents -- https://open-space.cloud/项目地址https://gitcode.com/gh_mirrors/opens/OpenSpace点击查看免费下载相关推荐OpenSpace Agent 技能实战用 head wc -l 合并调用实现最小化 Shell 往返开销OpenSpace Agent 技能实战用 head wc l 合并调用实现最小化 Shell 往返开销 导读 本文围绕 OpenSpace 技能库中的人工智能AI 技能MCP 服务AI 评测OpenSpace Agent 技能实战用 run_shell Python Heredoc 构建可靠代码执行回退shell-python-fallbackOpenSpace Agent 技能实战用 run_shell Python Heredoc 构建可靠代码执行回退shell python fallba人工智能AI 技能MCP 服务AI 评测在 Clojure 中为 shell 命令指定执行目录clojure.java.shell 的 with-sh-dir 与 :dir 用法在 Clojure 中为 shell 命令指定执行目录clojure.java.shell 的 with sh dir 与 :dir 用法 Clojure 通文档教程知识库上一篇Video2X让AI重新定义视频画质与流畅度的革命性工具下一篇WechatBakTool微信聊天记录备份工具数据安全保护的完整解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考