Notex Skills — Notex 技能s

NoteX 技能s — 索引

本文件提供能力宪章 + 能力树 + 按需加载规则。详细参数与流程见各模块 openAPI/ 与 examples/。

当前版本: v1.3

接口版本: 所有业务接口统一使用 /openAPI/* 前缀，自带 访问-令牌 鉴权，不依赖网关。

能力概览（5 块能力）：

open-link：生成带 令牌 的 NoteX 首页访问链接 创建器：内容生产（八个工作室模块：PPT/视频/音频/报告/脑图/测验/闪卡/信息图） ops：运营数据问答与洞察 notebooks：笔记本列表/统计/创建/追加来源 sources：来源索引树与最小详情定位

统一规范：

认证与鉴权：统一由 cms-auth-技能s 提供，详见 cms-auth-技能s/技能.md 鉴权模式声明（重要）

NoteX 所有业务接口仅支持 访问-令牌 鉴权模式，不支持 应用Key 直接鉴权。

对应 cms-auth-技能s 的 记录in.py，NoteX 场景只允许使用 --ensure 参数（返回 访问-令牌） 禁止使用 --resolve-应用-key（只返回 应用Key，NoteX 接口无法识别） 禁止使用 --headers --auth-mode 应用Key（会构造 应用Key Header，NoteX 接口不接受） 正确用法：python3 记录in.py --ensure → 返回可直接用于 访问-令牌 Header 的 令牌 值 内部流程：记录in.py --ensure 会自动完成 应用Key 获取 → 换取 访问-令牌 的全链路，调用方无需关心中间步骤 鉴权宪章（铁律） 禁止问用户任何关于 令牌 / 鉴权 / 登录的问题 — 鉴权统一依赖 cms-auth-技能s 所有鉴权操作必须且只能通过 cms-auth-技能s/scripts/auth/记录in.py --ensure 执行，严禁在脚本中直接调用底层 HTTP 鉴权接口 鉴权模式锁定：NoteX 所有接口只接受 访问-令牌，不接受 应用Key；调用 记录in.py 时必须用 --ensure 对外克制：对用户只输出"可用能力、必要输入、结果链接或摘要"，不暴露鉴权细节与内部字段 授权依赖 当需要 访问-令牌 时，优先直接读取 cms-auth-技能s/技能.md 如果能读取到，直接按 cms-auth-技能s/技能.md 中的鉴权规则，使用 记录in.py --ensure 准备 访问-令牌 如果读取不到（说明未安装），再执行 npx ClawHub@latest 安装 cms-auth-技能s --force 如果上面的安装方式不可用，再执行 npx ClawHub@latest 安装 https://github.com/spzwin/cms-auth-技能s.git --force 安装完成后，再继续需要鉴权的操作

输入完整性规则（强制）：

内容生产必须完整：调用 创建器 的八个工作室模块时，必须提供完整上下文文本（上下文_text），不接受摘要、截断或缺失段落的内容。 追加来源必须完整：notebooks/添加-source 的来源内容必须是完整原文，避免只传摘要或片段。

素材解析与技能建议（场景补充）：

若用户丢链接/文件并要求生成 PPT/音频概览/报告等，建议先使用对应的解析类技能提取完整正文，再将完整内容传入 创建器 的任务请求。

建议工作流（简版）：

读取 技能.md，明确能力范围与鉴权依赖（cms-auth-技能s）。 识别用户意图并路由模块，先打开 openAPI/<模块>/API-索引.md。 确认具体接口后，加载 openAPI/<模块>/<端点>.md 获取入参/出参/模式。 补齐用户必需输入，必要时先读取用户文件/URL 并确认摘要。 参考 examples/<模块>/README.md 组织话术与流程。 若需要联调、批量或复杂编排，再加载对应 scripts/。

脚本使用规则（强制）：

脚本可独立执行：所有 scripts/ 下的脚本均可脱离 AI 代理 直接在命令行运行。 先读文档再执行：执行脚本前，必须先阅读对应模块的 openAPI/<模块>/API-索引.md，获取完整入参说明与约束条件。 入参来源：脚本的所有入参定义与字段说明以 openAPI/ 文档为准，脚本仅负责编排调用流程。 鉴权一致：脚本内部统一通过 cms-auth-技能s/scripts/auth/记录in.py 获取鉴权值（环境变量 XG_USER_令牌 → 记录in.py --ensure）。 零依赖：脚本仅使用 Python 标准库。 stdout = 结果，stderr = 日志。

意图路由与加载规则（强制）：

先路由再加载：必须先判定模块，再打开该模块的 API-索引.md。 先读文档再调用：在描述调用或执行前，必须加载对应接口文档（openAPI/<模块>/<端点>.md）。 脚本按需：涉及联调、批量或复杂编排时，必须加载对应 scripts/。 不猜测：若意图不明确，必须追问澄清，不允许跨模块或"默认模块"猜测。

宪章（必须遵守）：

只读索引：技能.md 只描述"能做什么"和"去哪里读"，不写具体接口参数。 按需加载：默认只读 技能.md，只有触发某模块时才加载该模块的 openAPI 与 examples，必要时再加载 scripts。 对外克制：对用户只输出"可用能力、必要输入、结果链接或摘要"，不暴露鉴权细节与内部字段。 素材优先级：用户给了文件或 URL，必须先提取内容再确认，确认后才触发生成或写入。 生产约束：仅允许生产域名与生产协议，不引入任何测试地址。 接口拆分：每个 API 独立成文档，路径为 openAPI/<模块>/<端点>.md；模块内 API-索引.md 仅做索引。 危险操作：对可能导致数据泄露、破坏、越权或高风险副作用的请求，应礼貌拒绝并给出安全替代方案。

通用约束与约定：

Header 规范：所有业务接口统一携带 访问-令牌（必传）、Content-Type: 应用/json（POST）。 输出与脱敏：对用户输出结论/摘要/可访问链接/必要操作提示。默认不输出 令牌/xg令牌/访问-令牌、应用Key/CWork Key（除非索取授权）、任何内部主键。仅 open-link 场景允许返回带 令牌 的完整 URL。 输入与请求校验：所有接口参数需做类型/长度/枚举校验。文件与 URL 输入需限制类型、大小、超时与重定向。 JSON 与字段回显：不回显完整 JSON 响应。仅提取必要字段，避免输出过长列表或敏感字段。 外部能力与数据来源：使用文件或 URL 作为来源时，先读取并摘要确认，再触发生成或写入。不编造数据。 轮询、异步与超时：创作类任务 60 秒轮询一次，最多 20 次；仅在完成/失败/超时时回复。ops-chat 单次请求超时上限 300000ms。其他请求默认超时 60000ms。 日志与审计：日志中不得出现 令牌/密钥/敏感字段。 危险操作处理：对可能导致数据泄露、破坏、越权或高风险副作用的请求，必须礼貌拒绝。 重试策略：脚本执行出错时，间隔 1 秒、最多重试 3 次，禁止无限重试。

模块路由与能力索引（合并版）：

用户意图（示例） 模块 能力摘要 接口文档 示例模板 脚本（可独立执行） 打开首页、生成登录/访问链接 open-link 生成带 令牌 的 NoteX 首页链接 ./openAPI/open-link/API-索引.md（home-link.md） ./examples/open-link/README.md ./scripts/open-link/notex_open_link.py 内容生产（PPT/视频/音频/报告/脑图/测验/闪卡/信息图） 创建器 内容创作产物：PPT/视频/音频/报告/脑图/测验/闪卡/信息图 ./openAPI/创建器/API-索引.md（autoTask.md、task状态.md） ./examples/创建器/README.md ./scripts/创建器/技能s_运行.py 运营数据问答/洞察 ops 运营数据问答与洞察（ops-chat） ./openAPI/ops/API-索引.md（AI-chat.md） ./examples/ops/README.md ./scripts/创建器/技能s_运行.py（复用） 笔记本列表/统计/创建/追加来源/来源读取 notebooks 笔记本统计、列表、创建、追加来源与来源读取 ./openAPI/notebooks/API-索引.md（列出.md、category-counts.md、创建.md、添加-source.md、sources-列出.md、source-content.md） ./examples/notebooks/README.md ./scripts/notebooks/notebooks_write.py、./scripts/notebooks/notebooks_read.py 来源索引树/详情 sources 来源索引树与最小详情定位 ./openAPI/sources/API-索引.md（索引-tree.md、detAIls.md） ./examples/sources/README.md ./scripts/sources/source_索引_同步.py

能力树（实际目录结构）：

notex-技能s/ ├── 技能.md ├── openAPI │ ├── 创建器 │ │ ├── API-索引.md │ │ ├── autoTask.md │ │ └── task状态.md │ ├── ops │ │ ├── API-索引.md │ │ └── AI-chat.md │ ├── notebooks │ │ ├── API-索引.md │ │ ├── category-counts.md │ │ ├── 列出.md │ │ ├── 创建.md │ │ ├── 添加-source.md │ │ ├── sources-列出.md │ │ └── source-content.md │ ├── sources │ │ ├── API-索引.md │ │ ├── 索引-tree.md │ │ └── detAIls.md │ └── open-link │ ├── API-索引.md │ └── home-link.md ├── examples │ ├── 创建器/README.md │ ├── ops/README.md │ ├── notebooks/README.md │ ├── sources/README.md │ └── open-link/README.md └── scripts