CyberStrikeAI 技能包引用目录解析：citations.md 与 HTTP resource_path / 多代理文件工具的验证路径-港品优选

CyberStrikeAI 技能包引用目录解析：citations.md 与 HTTP resource_path / 多代理文件工具的验证路径

【免费下载链接】CyberStrikeAIThe system of action for AI-native cybersecurity—where intent becomes governed execution, evidence becomes operational memory, and every operation improves the next.项目地址: https://gitcode.com/GitHub_Trending/cy/CyberStrikeAI

本文围绕 CyberStrikeAI 仓库中技能包cyberstrike-eino-demo的references/citations.md文件展开，说明references/目录在技能包（Skill Package）中扮演的角色：它既承担外部引用与出处记录的职责，也是验证列表 API、HTTPresource_path资源读取、多代理本机文件工具三条访问路径是否打通的关键测试样本。读完本文，你将掌握 CyberStrikeAI 中技能包资源的完整访问链路（HTTP 列表 → 包内资源读取 → Eino 多代理渐进加载），并能用同样的方法检验任意技能包（如仓库skills/目录下的 20+ 个渗透测试技能）的包内文件是否被正确索引与读取。

背景：技能包与 references/ 目录的定位

CyberStrikeAI 将技能（Skills）组织为技能包：每个技能包是一个目录，核心入口为SKILL.md（清单 + 主说明，无需单独的SKILL.yaml），同目录下可附带scripts/、references/、assets/等任意子目录，只要路径安全、未触达包深度与文件数上限即可。

以 skills/cyberstrike-eino-demo/ 这个"满配示例技能包"为例，其结构为：

skills/cyberstrike-eino-demo/ ├── SKILL.md # 清单 + 主说明（frontmatter: name/description） ├── FORMS.md # 补充说明：表单/输出格式 ├── REFERENCE.md # API / 参考（示例） ├── references/ │ └── citations.md # 引用与外链（示例）—— 本文主角 ├── assets/ │ └── README.txt # 占位资源 └── scripts/ ├── check-env.sh # 环境检查脚本 ├── payloads.txt # Payload 样例列表 └── report-snippet.json# 报告 JSON 片段模板

在该包中，references/citations.md的定位非常清晰：验证非scripts/子目录是否被同等对待。这一点在 SKILL.md 的"references/ 与 assets/"一节中有明确对应：

路径	用途
`references/citations.md`	引用与 HTTP`resource_path`测试说明
`assets/README.txt`	占位资源（可换成真实二进制做读文件上限测试）

因此，citations.md看似只有十几行，实际是技能包"包内文件索引与读取"能力的验收探针：只要它被列表 API 列出、被resource_path读取、被多代理文件工具读到，就证明该技能包的资源管理链路完整可用。

citations.md 的测试主张：三条验证路径

references/citations.md声明的验证方式共三条，全部限定在授权环境内：

GET /api/skills/cyberstrike-eino-demo响应中的package_files应包含references/citations.md；
GET /api/skills/cyberstrike-eino-demo?resource_path=references/citations.md应返回本文内容；
多代理且开启eino_skills.filesystem_tools时，可通过相对路径读取本文件。

此外，文件末尾的"占位引用"给出了一个外部链接格式示例（OWASP Testing Guide），并注明仅作链接格式示例——这正是references/目录的另一层语义：作为引用与出处的集中存放位置，帮助 Agent 与读者回溯外部标准。

下面逐一深入这三条路径的源码实现与实操验证。

路径一：列表 API 的 package_files 索引

第一条验证对应技能列表/详情接口。在 HTTP 层，GET /api/skills/{name}由 internal/handler/skills.go 的GetSkill处理，其响应体包含"package_files": skill.PackageFiles（见 skills.go#L241），即包内全部文件的索引列表。

PackageFiles来源于skillpackage包。查看 internal/skillpackage/service.go 中的LoadSkill：它通过ListPackageFiles(skillsRoot, skillID)扫描技能包目录（service.go#L104），随后将结果写入SkillView.PackageFiles（service.go#L125）。

值得注意的是loadSummary（service.go#L28-L78）中计算FileCount时对ListPackageFiles结果做了非目录过滤，说明目录与文件都会被列进包内文件清单，但只有文件计入 file_count。这正是citations.md能被package_files覆盖的结构性保证：ListPackageFiles递归扫描包目录，references/下的普通文件自然在列。

除详情接口外，列表接口同样体现该文件的存在：loadSummary从SKILL.md解析清单并推导ScriptCount、FileCount、Progressive等字段（service.go#L63-L77），这些推导/扫描结果即 SKILL.md 概述中提到的列表 API 返回字段。也就是说，references/citations.md不仅在详情里可见，还会让技能的file_count相应 +1。

实操验证

# 列表（摘要级）应能看到 cyberstrike-eino-demo 及其 file_count 等扫描字段 curl -s "http://<host>:<port>/api/skills?keyword=cyberstrike-eino-demo" # 详情（full 深度）的 package_files 应包含 references/citations.md curl -s "http://<host>:<port>/api/skills/cyberstrike-eino-demo?depth=full" \ | jq '.skill.package_files[] | select(.rel_path=="references/citations.md")'

depth参数仅支持summary或full（skills.go#L199-L210）：depth=summary只返回摘要与目录，适合首轮检索；depth=full（默认）返回完整正文与包文件清单。

路径二：HTTP resource_path 精确读取包内资源

第二条验证是resource_path参数。仍看GetSkill（skills.go#L176-L197）：当请求携带resource_path（兼容旧参数skill_script_path）时，直接调用skillpackage.ReadScriptText(h.skillsRootAbs(), skillName, resPath, 0)读取包内文件内容并以{"resource": {"path": ..., "content": ...}}结构返回；读取失败则返回 404。

ReadScriptText（service.go#L149-L155）是对ReadPackageFile的薄封装，其中maxBytes参数传入 0 表示不设上限读取。这意味着resource_path不仅能读scripts/payloads.txt这类脚本，也能读references/citations.md、assets/README.txt这类非脚本资源，这正是 SKILL.md 清单项"resource_path=references/citations.md与resource_path=assets/README.txt可读取"所验证的内容。

从包内路径校验角度看，ReadPackageFile/ListPackageFiles所属的skillpackage包（internal/skillpackage/io.go、internal/skillpackage/layout.go）负责路径安全约束，确保相对路径不会逃逸出技能包目录——这也是 SKILL.md 强调"只要路径安全"的原因。

实操验证

# 精确读取 references/citations.md curl -s "http://<host>:<port>/api/skills/cyberstrike-eino-demo?resource_path=references/citations.md" # 读取脚本资源（同样走 resource_path） curl -s "http://<host>:<port>/api/skills/cyberstrike-eino-demo?resource_path=scripts/check-env.sh"

配套能力：section 分块读取

与resource_path同属渐进加载体系的还有section参数（skills.go#L200）。LoadSkill内部通过splitMarkdownSections将SKILL.md按##标题切块，findSectionContent支持用标题或 ASCII 短 id 命中（如## Payload 样例对应section=payload，见 service.go#L131-L141）。这为 Agent 提供了按需取段的能力：先depth=summary拿骨架，再section=取指定小节，最后resource_path=拉完整脚本。

路径三：多代理本机文件工具读取包内相对路径

第三条验证面向多代理（Multi-Agent）运行时。技能包说明文档 REFERENCE.md 明确：多代理环境下使用 Eino ADK 的skill工具按技能包渐进加载；可选开启multi_agent.eino_skills.filesystem_tools访问包内文件。

该配置项在 internal/config/config.go 中有精确定义。MultiAgentEinoSkillsConfig（config.go#L445-L453）包含三个字段：

multi_agent: eino_skills: disable: false # true 时跳过 skill 中间件，且不为 Deep 附加本机 FS 工具 filesystem_tools: true # 注册 read_file/glob/grep/write/edit/execute（eino-ext 本地后端）；缺省即 true skill_tool_name: "skill" # 覆盖默认 Eino 工具名 "skill"

关键点在于EinoSkillFilesystemToolsEffective()（config.go#L456-L461）：filesystem_tools缺省（nil）时视为 true。也就是说，除非显式关闭，多代理环境默认就具备通过本机文件工具按相对路径读取技能包内文件的能力——这保证references/citations.md在代理会话中可直接以相对路径被读到。

配置注释（config.go#L446-L452）进一步说明：Disable跳过 skill 中间件的同时也不会为 Deep 附加本机 FS 工具；filesystem_tools注册的是read_file/glob/grep/write/edit/execute一组工具（eino-ext 本地后端）。与 HTTP 通道相比，多代理文件工具是同一包内资源的另一种访问形态：HTTPresource_path面向外部 API 调用者，本机文件工具面向 Agent 内部推理循环，两者互为印证。

验证要点

多代理会话中调用skill工具加载cyberstrike-eino-demo（渐进加载，节省 token）；
需要脚本原文时用本机文件工具读取scripts/check-env.sh、references/citations.md等相对路径；
用FORMS.md、REFERENCE.md验证非scripts/的补充文档同样可读。

技能包清单与验证闭环

综合 SKILL.md 的"清单与验证"一节，citations.md对应着如下可勾选验收项：

已保存书面授权与测试窗口（citations.md与 SKILL.md 都强调"仅授权安全测试与教学"这一硬性要求）；
scripts/下文件与正文引用一致；
Web 或GET /api/skills?...可核对索引；多代理会话内用skill工具按包加载以节省 token；
需要细节时通过skill拉全文，或 HTTPdepth=full、section=<标题或短 id>；
需要脚本原文时通过本机文件工具或 HTTPresource_path=scripts/check-env.sh；
resource_path=references/citations.md与resource_path=assets/README.txt可读取。

在仓库中，cyberstrike-eino-demo的包内资源与技能管理界面的对应关系可直接在 images/skills.png 中看到：技能管理页面左侧目录树完整展示了references/citations.md、assets/README.txt、scripts/payloads.txt等包内文件，右侧为SKILL.md的内容编辑区，与本文所述的列表索引、资源读取能力一一对应。

将 citations.md 模式推广到其他技能包

references/citations.md的验证模式可复用到仓库 skills/ 目录下的所有技能包——例如web-attack-methods、cloud-attack-methods、active-directory-attack、source-code-hunting等 20+ 个技能。当你新增或维护一个技能包时，遵循同一套约定：

references/放引用与出处：外部标准、工具文档链接、来源说明集中于此，便于审计与溯源（如citations.md中的 OWASP Testing Guide 占位链接即此类用途）；
scripts/放可执行资产：check-env.sh类环境检查脚本、payloads.txt类载荷清单；
assets/放二进制/大文件：可借ReadPackageFile的maxBytes参数验证读文件上限；
SKILL.md是唯一入口：name、description等 frontmatter 驱动列表 API 的摘要推导（service.go#L38-L44），正文##标题驱动section=分块。

每次调整包结构后，用本文的三条路径做回归：列表 API 是否列出新文件 →resource_path是否可读 → 多代理文件工具是否可访问。三者全绿，即证明该技能包已完整接入 CyberStrikeAI 的"列表 → 渐进加载 → 资源读取"链路，能被 HTTP 客户端与 Eino 多代理无缝消费。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析