docxology/CogSecSkills

# CogSecSkills [](https://doi.org/10.5281/zenodo.20804585) [](https://github.com/docxology/CogSecSkills/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) **用于认知安全与分析专业的 Agentic 工具使用技能** —— 一个包含 **100 项分析技能**（结构化分析技术、认知安全防御、OSINT 完整性、反情报和关键审查）的库，每项技能都作为**框架无关的技能**编写一次，并提供针对 Claude Code、Codex 和 Hermes 的默认 adapter，对于任何其他已配置的框架也具有相同的结构契约。 ## 安装说明 ``` git clone https://github.com/docxology/CogSecSkills.git cd CogSecSkills uv sync PYTHONPATH="src:." python -m cogsecskills validate # 0 errors over all 100 skills # 为分析需求找到合适的 skill，然后对其进行检查 python -m cogsecskills route "verify a viral claim before sharing it" python -m cogsecskills show sat.analysis_of_competing_hypotheses ``` 要连接 agent 框架，请将其指向 `skills///SKILL.md`，运行 `workflow.md`，并通过匹配的 `harness/.md` adapter 绑定工具。 完整的命令参考请见[用法](#usage)；框架详情请见 [`docs/harness-installation.md`](docs/harness-installation.md) 和 [`docs/harness-cookbook.md`](docs/harness-cookbook.md)。 ## 阅读与引用 - **手稿 (PDF):** [`CogSecSkills.pdf`](CogSecSkills.pdf) — 完整、可复现的技能系统报告（也附加在每个 release 中）。 - **Zenodo 存档:** 概念 DOI [10.5281/zenodo.20804585](https://doi.org/10.5281/zenodo.20804585)（始终 指向最新版本）；v1.0.0 版本 DOI [10.5281/zenodo.20804586](https://doi.org/10.5281/zenodo.20804586)。引用 元数据请见 [`CITATION.cff`](CITATION.cff)。 - **第一次接触？** [`QUICKSTART.md`](QUICKSTART.md) · **文档地图：** [`docs/README.md`](docs/README.md) 该库严格基于**防御性、教育性和可问责性**。其教育上游是 [AGEINT](docs/ageint/README.md) 课程。这些技能用于识别、评估和防御认知攻击——它们不用于策划操纵。 ## 三个连贯的产物 | 产物 | 角色 | 位置 | |----------|------|-------| | **教学** | 概念（*为什么*） | [`docs/ageint/`](docs/ageint/README.md) | | **计划** | 所有 100 个技能领域的目录（*是什么*） | [`registry/skills.yaml`](registry/skills.yaml) | | **构建** | 规范定义与渲染的多框架技能实现（*怎么做*） | [`definitions/`](definitions/) 和 [`skills/`](skills/) | `python -m cogsecskills validate` 保持“计划”和“构建”的一致性：磁盘上的每个 skill 都必须被编目，并且每个 `implemented` 的目录条目都必须存在。 ## 技能组（workflow 子文件夹） | 组别 | 重点 | 数量 | |-------|-------|-------| | `sat` | 结构化分析技术 (Heuer & Pherson) | 34 | | `cognitive_security` | 防御感知、推理、决策 | 24 | | `critical_review` | 对抗性 + 建设性审查（包含 **项目关键审查**） | 12 | | `osint_integrity` | 具备溯源规范的开源收集 | 10 | | `counterintelligence` | 拒止/欺骗检测、流程加固 | 8 | | `information_environment` | 叙事、影响力行动、协同行为 | 7 | | `research_methods` | 综合、证据评级、校准估算 | 5 | **所有 100 个领域均已完全实现**为合规的多框架技能文件夹 —— 每个都包含真实、技术准确的操作流程、合适的工具计划，以及在已配置的框架集下绑定所有已声明动词的 adapter。默认 配置的集合是 Claude Code、Codex 和 Hermes。 `python -m cogsecskills report` 显示实时计数（已实现：100）。 现在，所有 100 项技能在 `definitions/` 下都有持久化的规范定义。 `python -m cogsecskills definitions --write` 从该源层确定性地渲染完整的 `skills/` 树，而 `definitions --check` 证明定义与渲染的文件没有发生偏离。 `python -m cogsecskills scenarios --check` 在精选的安全使用和不安全重定向的 fixture 上增加了一个确定性的防御性就绪闸门；它检查路由、本地 skill 契约、预期的 response-shape 元数据，以及经过审查的预期答案 fixture，而无需调用外部模型 runtime。 `python -m cogsecskills examples --write` 从 `examples/skill-worked-examples.yaml` 中为每个技能生成一个可操作的防御性示例。 `python -m cogsecskills evals --write` 根据 scenario 的预期答案生成本地离线 output-review fixture 和报告；它不调用真实的模型。 `python -m cogsecskills dashboard --write` 生成一个 100 技能质量看板，用于 scenarios、离线 evals、worked examples、quality capsules、harnesses、references 和 source paths 的导航和漂移审查，包含 Markdown、静态 HTML 和 JSON 视图。 `python -m cogsecskills release-metadata --write` 生成本地 release claim matrix 和元数据快照，而不进行发布、打标签或归档。 确切的 git 修订版本、分支和 dirty-state 的值会在命令 runtime 被获取，而不是嵌入到已提交的生成文件中。 ## 技能结构剖析 ``` skills/// skill.yaml # generated harness-neutral spec SKILL.md # Claude Code native entry point (frontmatter + doc) workflow.md # the agentic procedure, each step tagged with a tool verb harness/ claude.md # default adapter: Claude Code tools codex.md # default adapter: Codex tools hermes.md # default adapter: Hermes function calls .md # optional configured harness adapter ``` 一项技能将其能力声明为**闭集工具动词**（`read`、`search`、`write`、`exec`、`reason`、`web`、`delegate`、`ask`）。每个 harness adapter 都会在 Markdown 绑定表中将这些动词绑定到具体的工具上。validator 会检查每个 adapter 中是否包含所有已声明的动词，因此“多框架”是测试套件*证明*的一个属性，而不是一种期望。 已编写技能实质内容的持久化真实数据源是 `definitions//.yaml`；`skill.yaml` 及其配套的 Markdown 文件是生成的、面向框架的构建输出。 ## 用法 ``` # 从 GitHub 安装并验证库 git clone https://github.com/docxology/CogSecSkills.git cd CogSecSkills uv sync PYTHONPATH="src:." python -m cogsecskills validate # 列出目录（全部 100 个领域） python -m cogsecskills list python -m cogsecskills list --group sat --status implemented # 检查单个 skill python -m cogsecskills show sat.analysis_of_competing_hypotheses # 为自由文本分析需求找到最佳 skill python -m cogsecskills route "verify a viral claim before sharing it" # 验证整个库（plan <-> build 一致性 + multiharness 一致性） python -m cogsecskills validate # JSON 状态报告 python -m cogsecskills report # 统计信息、分组目录和质量 lint python -m cogsecskills stats python -m cogsecskills catalogue --markdown --output docs/catalogue.md python -m cogsecskills doctor python -m cogsecskills scenarios --check python -m cogsecskills examples --write python -m cogsecskills examples --check python -m cogsecskills evals --write python -m cogsecskills evals --check python -m cogsecskills dashboard --write python -m cogsecskills dashboard --check python -m cogsecskills release-metadata --write python -m cogsecskills release-metadata --check # 从实时库重新生成稿件补充材料和图表 python -m cogsecskills manuscript-assets --write python -m cogsecskills manuscript-assets --check # 从 canonical YAML 定义重新生成所有已渲染的 skill python -m cogsecskills definitions --write python -m cogsecskills definitions --check # 从结构化 JSON/YAML 定义确定性地编写完整的 skill python -m cogsecskills author path/to/definition.yaml # render one python -m cogsecskills author-batch # compatibility path for skills/**/_def.json # 从 registry 搭建一个全新的计划领域（待深化的 skeleton） python -m cogsecskills scaffold sat.some_new_area ``` （在项目根目录下，使用 `PYTHONPATH="src:."` 或在执行 `uv sync` 后。） 要连接 harness，请将其指向 `skills///SKILL.md`，使用 `workflow.md` 作为中性流程，并通过匹配的 `harness/.md` adapter 绑定工具。默认配置的集合是 `claude`、`codex` 和 `hermes`；在 `cogsecskills.yaml` 中添加更多 harness，并使用 `python -m cogsecskills definitions --write` 重新生成 adapter。 关于有边界的示例，请参见 [`examples/harness-smoke-transcripts.md`](examples/harness-smoke-transcripts.md) [`examples/group-worked-examples.md`](examples/group-worked-examples.md)，和 [`docs/skill-worked-examples.md`](docs/skill-worked-examples.md)。 关于 claim 规范，请参见 [`docs/claim-boundaries.md`](docs/claim-boundaries.md)。 关于生成的质量看板，请参见 [`docs/quality-dashboard.md`](docs/quality-dashboard.md) 和 [`docs/quality-dashboard.html`](docs/quality-dashboard.html)。关于生成图表、封面图片、看板页面和手稿表格的视觉风格规则位于 [`DESIGN.md`](DESIGN.md) 中。 ## 8 个参考范例 （所有 100 个技能均已实现；这 8 个是人工编写的参考。） | 技能 | 组别 | |-------|-------| | `sat.analysis_of_competing_hypotheses` | 结构化分析技术 | | `sat.key_assumptions_check` | 结构化分析技术 | | `sat.devils_advocacy` | 结构化分析技术 | | `cognitive_security.narrative_threat_assessment` | 认知安全 | | `cognitive_security.source_credibility_evaluation` | 认知安全 | | `critical_review.project_critical_review` | 关键审查与保证 | | `osint_integrity.claim_provenance_verification` | OSINT 与来源完整性 | | `research_methods.structured_literature_synthesis` | 研究与综合方法 | ## 测试 ``` PYTHONPATH="src:." python -m pytest \ tests/test_cogsecskills_*.py tests/test_skill_library_conformance.py \ --cov=src/cogsecskills --cov-report=term-missing ``` 实时的 conformance 测试（`tests/test_skill_library_conformance.py`）会针对真实的 `skills/` 树运行：添加格式错误的 skill，或在没有构建产物的情况下添加 `implemented` 注册表条目，都会导致测试套件失败。 ## 溯源 - 规范的公共代码库：。 本地手稿/渲染验证可能会使用同级的 docxology 模板，但**交付物是技能系统**：registry、skills、AGEINT 文档、runner、测试、生成的手稿补充材料和描述这些源表面的图表。 - 归档的 release：Zenodo 上的 **v1.0.0** — 概念 DOI [10.5281/zenodo.20804585](https://doi.org/10.5281/zenodo.20804585)（所有 版本），版本 DOI [10.5281/zenodo.20804586](https://doi.org/10.5281/zenodo.20804586)。 处的 GitHub 发布包含了渲染好的手稿 PDF。 - 教育上游：[AGEINT](https://github.com/docxology/AGEINT) （概念 DOI [10.5281/zenodo.20732274](https://doi.org/10.5281/zenodo.20732274)）。 - 技能目录借鉴了 Heuer & Pherson 的《*Structured Analytic Techniques for Intelligence Analysis*》以及每个 primer 中引用的认知安全文献。 参见 [`ISA.md`](ISA.md) 以了解项目理想状态的表述和验收标准。

标签：AI智能体, Python, 分析技术, 提示词工程, 无后门, 策略决策点, 认知安全, 逆向工具