NanAquarius/Glassroom

[English](./README.md) | [简体中文](./README.zh-CN.md) # Glassroom [](./LICENSE) [](#quick-start) [](#what-glassroom-is) [](#installation) [](#module-families) [](https://github.com/NanAquarius/Glassroom/actions/workflows/ci.yml) Glassroom 是一个用于结构化情报分析的 CLI 和工作流核心。 它帮助将原始来源转化为可重用的输出，例如源包、偏差分析、结构化分析、共享案例对象，以及下游教学或写作产物。 ## 安装 ``` npx glassroom install openclaw npx glassroom install project ``` 当前可用命令： - `glassroom install openclaw` - `glassroom install project` - `glassroom list-skills` - `glassroom assemble case` 版本命令： - `glassroom --version` - `glassroom version` 仅安装选定的技能： ``` npx glassroom install openclaw --skills glassroom-router,glassroom-source-intake ``` 列出可用技能： ``` npx glassroom list-skills ``` 组装一个共享案例对象： ``` glassroom assemble case \ --base-case examples/base-case.json \ --source-card examples/source-card.json \ --bias-analysis examples/bias-analysis.json \ --mitigation-pack examples/mitigation-pack.json \ --structured-analysis examples/structured-analysis.json \ --out-json /tmp/glassroom-case.json \ --out-md /tmp/glassroom-case.md ``` 如果 npm 不可用，请参见 [安装指南](#installation) 获取 GitHub 和手动备用路径。 ## ✨ 什么是 Glassroom Glassroom 不仅仅是一个智能体提示包，也不只是一个单一技能。 它是一个包含两个层次的项目： - 一个工作流核心 - 共享案例对象 - 中间产物 - 可重用分析模块 - 集成层 - 可挂载的 OpenClaw 技能 - CLI 界面 - 公开安全的文档与模板 当你需要一个能够将： - 将碎片化分析输出转化为共享案例对象 - 保持来源、偏差、缓解和结构化分析层相互关联 - 支持下游 HTML 教学页面或写作交付物 - 暴露可重用的模式而非将逻辑困在一次性提示中 - 保留教学模式，使其超越单个课堂产物 的工作流时，请使用 Glassroom。 ## 🚫 Glassroom 不是 它并非试图成为： - 一个通用文章生成器 - 一堆无关的课堂提示 - 一个课堂拥有产物的直接发布渠道 - 在核心工作流契约稳定之前，就成为一个完整的终端用户平台 开源规则很简单：先发布可移植的骨干，然后添加可独立存在的公开安全模块。 ## ⚡ 快速开始 目前最快的路径是从公开安全的示例输入组装一个共享案例对象。 ### CLI 路径 ``` glassroom assemble case \ --base-case examples/base-case.json \ --source-card examples/source-card.json \ --bias-analysis examples/bias-analysis.json \ --mitigation-pack examples/mitigation-pack.json \ --structured-analysis examples/structured-analysis.json \ --out-json /tmp/glassroom-case.json \ --out-md /tmp/glassroom-case.md ``` ### 包脚本路径 ``` python3 packages/case-assembler/assemble_case.py \ --base-case examples/base-case.json \ --source-card examples/source-card.json \ --bias-analysis examples/bias-analysis.json \ --mitigation-pack examples/mitigation-pack.json \ --structured-analysis examples/structured-analysis.json \ --out-json /tmp/glassroom-case.json \ --out-md /tmp/glassroom-case.md ``` 你也可以直接运行公开分析模块： ``` python3 packages/cognitive-bias/build_bias_analysis.py \ --input examples/bias-input.json \ --out-json /tmp/bias-analysis.json \ --out-md /tmp/bias-analysis.md python3 packages/structured-analysis/build_structured_analysis.py \ --input examples/structured-analysis-input.json \ --out-json /tmp/structured-analysis.json \ --out-md /tmp/structured-analysis.md python3 packages/source-intake/fetch_source_bundle.py \ --input examples/source-input.json \ --out-json /tmp/source-bundle.json \ --out-md /tmp/source-bundle.md ``` ## 📦 安装 Glassroom 自带一个安装器 CLI。 首选安装路径是 npm。 ### 从 npm 安装 安装到 OpenClaw 工作区： ``` npx glassroom install openclaw ``` 安装到当前项目工作区： ``` npx glassroom install project ``` 仅安装选定的技能： ``` npx glassroom install openclaw --skills glassroom-router,glassroom-source-intake ``` 列出可用的 Glassroom 技能： ``` npx glassroom list-skills ``` ### GitHub 备用方案 如果 npm 不可用，你可以直接从 GitHub 运行 Glassroom： ``` npx github:NanAquarius/Glassroom install openclaw npx github:NanAquarius/Glassroom install project npx github:NanAquarius/Glassroom list-skills ``` ### AI CLI 的单句安装提示 适用于 Claude Code、OpenCode 或类似的编码代理 CLI： ``` Run `npx glassroom install project` in this workspace and tell me which Glassroom skills are now available. ``` 如果该工具可以访问你的 OpenClaw 工作区： ``` Run `npx glassroom install openclaw` and tell me which Glassroom skills were installed into ~/.openclaw/workspace/skills/. ``` ### 手动安装备用方案 如果你希望使用手动路径而非安装器 CLI，可以克隆仓库并将 `skills/` 文件夹复制或链接到以下任一位置： - `~/.openclaw/workspace/skills/` - `./skills/` 安装器的作用是使这一过程更短、更干净、更易重复。 ## 🧩 当前公开范围 本次公开发布包括： - 一个共享的 Glassroom 案例模式（包含必需的 `caseId` 和 `title` 字段） - 描述模块如何丰富该模式的工作流契约 - `case-assembler` - `cognitive-bias` - 现在包含一个扩展的内置偏差目录，带有基于技艺的缓解步骤 - `structured-analysis` - 现在包含方法参数验证 - `source-intake` - 现在包含 URL 方案验证（SSRF 预防）和网络特定错误处理 - 共享工具层（`packages/shared/`），消除所有 Python 模块间的代码重复 - 所有模块加固的错误处理（窄异常、JSON 解析错误、返回类型注解） - 覆盖所有核心模块、共享工具和源包提取的 135 个单元测试 - 通过 GitHub Actions 的 CI — ruff 格式检查、mypy 类型检查、覆盖率报告、Python 3.11–3.13、Node.js 18/20/22 - 带有项目元数据、ruff 校验、mypy 和覆盖率配置的 `pyproject.toml` - 作为 `packages/` 委托的薄包装器技能脚本（单一事实来源） - 一个去标识化的 UI 模板参考库 - 一个可挂载的开源 `skills/` 层 - 一个带有安装命令和首个真实分析命令 `assemble case` 的 CLI 目标是并非一次性倾倒所有内容，而是先开放稳定的骨干，再从那里扩展。 ## 🗺 工作流工件映射 当前核心流程如下： ``` partial analysis artifacts → shared case object → reusable intermediate outputs → HTML pages / writing deliverables / teaching artifacts ``` 一个更具体的流程版本是： ``` base-case.json + source-card.json + bias-analysis.json + mitigation-pack.json + structured-analysis.json → glassroom-case.json → glassroom-case.md ``` 这个结构为你带来的好处： - 一个可重用的工作单元，而非多个分散的输出 - 模块之间更清晰的手动交接 - 更易渲染为多种下游格式 - 减少被困在单一位置的一次性提示中的逻辑 ## 🔧 共享工作单元 Glassroom 使用共享的 **案例对象** 作为默认工作单元。 参见： - [`schemas/glassroom-case.schema.json`](./schemas/glassroom-case.schema.json) - [`docs/workflow-contract.md`](./docs/workflow-contract.md) 并非每个模块都需要所有字段。 但共享模式是骨干，使来源摄入、偏差分析、结构化分析、缓解、渲染和写作输出能够相互通信。 ## 🧱 模块家族 ### 包层 - [`packages/shared/`](./packages/shared/) - 共享工具（`load_json`、`write_json`、`uniq` 等），供所有分析模块使用 - [`packages/case-assembler/`](./packages/case-assembler/) - 将部分输出合并为一个可重用的案例对象 - [`packages/cognitive-bias/`](./packages/cognitive-bias/) - 将候选偏差和摘录转化为可重用的偏差分析产物 - 偏差目录外部化为 `bias_catalog.json`，便于维护和扩展 - [`packages/structured-analysis/`](./packages/structured-analysis/) - 将策略问题、假设、证据转化为结构化分析产物 - [`packages/source-intake/`](./packages/source-intake/) - 获取、分类并结构化源材料，提供考虑提供者意识的检索以增强上游证据 - 自动重试并采用退避策略处理瞬态网络错误 ### 测试层 - [`tests/`](./tests/) - 135 个单元测试，覆盖共享工具、案例组装器、认知偏差、源卡片、源包提取和结构化分析模块 - 使用 `python -m unittest discover -s tests -v` 运行 ### 集成层 - [`skills/glassroom-router/`](./skills/glassroom-router/) - [`skills/glassroom-source-intake/`](./skills/glassroom-source-intake/) - [`skills/glassroom-case-assembler/`](./skills/glassroom-case-assembler/) - [`skills/glassroom-cognitive-b/`](./skills/glassroom-cognitive-bias/) - [`skills/glassroom-structured-analysis/`](./skills/glassroom-structured-analysis/) - [`bin/glassroom.js`](./bin/glassroom.js) 这些集成层位于包层之上。 技能脚本是薄包装器，将所有分析逻辑委托给 `packages/`，保持单一事实来源。`bin/` 层提供面向 CLI 的入口点。 ## 🎨 UI 模板库 Glassroom 还包含一个公开安全 UI 模板库的起点： - [`docs/ui-template-library/README.md`](./docs/ui-template-library/README.md) - [`docs/ui-template-library/templates/`](./docs/ui-template-library/templates/) - [`docs/ui-template-library/reference-pages/`](./docs/ui-template-library/reference-pages/) 该库用于在去标识化后保留可重用的教学页面结构。 它并非课堂拥有页面的转储。 规则是：在移除个人、讲师、课程所有者和来源特定身份标记的同时，保留教学流程、信息架构和可重用 UI 逻辑。 ## 🗂 仓库布局 ``` Glassroom/ ├── .github/ │ └── workflows/ │ └── ci.yml ├── bin/ ├── docs/ │ └── ui-template-library/ ├── examples/ ├── packages/ │ ├── shared/ ← shared utilities (load_json, write_json, uniq …) │ ├── case-assembler/ │ ├── cognitive-bias/ │ ├── source-intake/ │ └── structured-analysis/ ├── schemas/ ├── skills/ ← thin wrappers delegating to packages/ │ ├── glassroom-router/ │ ├── glassroom-source-intake/ │ ├── glassroom-case-assembler/ │ ├── glassroom-cognitive-bias/ │ └── glassroom-structured-analysis/ ├── tests/ │ ├── conftest.py │ ├── test_shared_utils.py │ ├── test_bias_analysis.py │ ├── test_case_assembler.py │ ├── test_fetch_source_bundle.py │ ├── test_source_card.py │ └── test_structured_analysis.py ├── package.json ├── pyproject.toml ├── CHANGELOG.md ├── CONTRIBUTING.md ├── SECURITY.md ├── .gitignore ├── LICENSE ├── README.md └── README.zh-CN.md ``` ## 🧪 测试 运行完整测试套件： ``` python -m unittest discover -s tests -v ``` CI 在推送到 `main` 和拉取请求时自动运行： 1. **Lint** — ruff 检查 + 格式验证 2. **类型检查** — mypy 静态类型分析 3. **Python 测试** — unittest 覆盖率测试，覆盖 Python 3.11/3.12/3.13 4. **CLI 冒烟测试** — 版本、帮助和跨 Node.js 18/20/22 的 list-skills ## 🛣 路线图方向 近期优先事项： 1. 强化围绕真实分析命令的 CLI 2. 扩展来源摄入覆盖范围 3. 暴露更多可重用渲染器和交付层 4. 保持 OpenClaw 集成轻薄且基于包 计划中的公开模块家族仍包括： - OSINT 陷阱与缓解 - 案例 HTML 渲染 - 课程写作输出 ## 📐 设计原则 - 优先稳定结构而非巧妙推断 - 使中间产物可重用 - 保持共享模式可在各模块间恢复 - 分离工作流编排与表示层 - 仅公开安全、可移植、可维护的内容 ## 📌 状态 Glassroom 仍处于早期提取阶段。 但它已超越“仅文档”阶段：核心契约是公开的，第一个分析模块是公开的，第一个去标识化的 UI 参考模式是公开的，CLI 现在包含安装流程和首个真实分析命令 `assemble case`。 随着更多本地 Glassroom 系统被公开，模式、示例、模块边界和公开安全渲染层将持续改进。 自 v0.3.1 起，项目已全面优化：所有正则表达式模式在模块级别预编译，输入验证防止格式错误的 JSON 字段，URL 获取包含带退避的重试机制，偏差目录已外部化为 JSON 以便更轻松维护，测试套件从 78 个增长到 135 个并覆盖源包提取。CI 现在包含 mypy 类型检查和覆盖率报告，以及 ruff 校验。 ## 参考书籍 以下两本书现已作为工作参考集的一部分： - *OSINT Techniques: Resources for Uncovering Online Information* — Michael Bazzell, Jason Edison (2024) - *Structured Analytic Techniques for Intelligence Analysis* — CQ Press (2020) ## 许可证 MIT ## 更新日志 参见 [CHANGELOG.md](./CHANGELOG.md)。 ## 贡献指南 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 安全信息 参见 [SECURITY.md](./SECURITY.md)。

标签：CI持续集成, GNU通用公共许可证, Markdown文档, MITM代理, Node.js, Python, Shell脚本, 下游教学, 二进制发布, 偏见分析, 写作辅助, 可重用案例, 安装技能, 工作流核心, 应用安全, 开源工具, 情报分析, 技能管理, 无后门, 智能分析, 案例对象, 案例组装, 源码摄入, 结构化分析, 结构化输出, 网络诊断, 路由模块, 逆向工具