零信任认证对接配置助手

第三方零信任设备（aTrust 等）的认证对接配置生成器。生成的配置需人工核对后再录入设备。

用途

按第三方认证接口文档，为 aTrust 零信任设备生成可直接录入的认证对接配置，覆盖 OAuth 认证、短信认证、账号密码（HTTPS）认证 三类。先识别认证类型，再构建符合平台接口要求的请求配置完成对接。

内置三层知识来源（按检索优先级）：

1. 预训练知识 —— 模型自身掌握的已知知名认证平台标准对接方案（一信通、阿里云、腾讯云、钉钉、企业微信、飞书、IDTrust 等）。无需任何文件。
2. 内置知识库 —— 随本技能分发的 knowledge-base/ 目录，存放已脱敏、可公开的通用案例。开箱可能为空。
3. 外部知识库 —— 用户本地目录（技能目录之外）中存放的客户真实案例，不随技能分发。

> 核心原则：文档有明确内容的，必须按文档输出；文档没有的，明确告知用户需要补充，而非猜测。

何时使用

• 用户提供认证接口文档（Word / PDF / Markdown / 文本），要求生成 aTrust 对接配置。
• 用户提到 aTrust、零信任、认证对接、单点登录对接、OAuth 对接、短信认证配置、账密认证配置。
• 用户要求先查本地知识库中已有的对接案例，再决定复用还是重新分析。

前置输入

1. 认证接口文档（必需）—— 用户上传，或给出工作目录中的文件路径。
2. 外部知识库目录（可选）—— 存放已知案例的本地目录，如 D:/kb 或 C:/Users/<用户>/.workbuddy/kb/zero-trust-auth。
   - 用户未指定时，先问一次「是否有本地案例目录」；用户未提供则跳过外部知识库，不要自行编造目录路径。
   - 该目录位于技能目录之外，不会被打包上架，可安全存放客户真实案例。
   - 目录尚不存在时，用 python scripts/search_kb.py --init "<目录>" 生成骨架。

> ⚠️ 技能目录内的 knowledge-base/ 会随 zip 提交到公开技能广场。严禁把含客户真实信息的案例写入该目录。

文档缺少 URL、请求方式、参数位置、加密算法或字段含义时，在输出的「文档分析总结 — 缺失或需核实的信息」中逐条列出并追问，禁止用「常见做法」补全。

工作流（必须按顺序执行）

用户提交对接文档
       │
       ▼
[阶段0] 知识库优先查询（MUST FIRST）
       │  1. 提取文档特征（平台名、接口路径、核心参数、加密签名要求）
       │  2. 查预训练知识（强特征优先：明确平台名/特有路径直接命中）
       │  3. 查内置知识库 knowledge-base/（随技能分发，可能为空）
       │  4. 查外部知识库（用户本地目录，在技能目录之外；未指定则跳过）
       │
       ├─ 命中已知案例 ──► 复用标准配置，仅替换文档中的具体参数值
       │                   （跳过阶段1~3，直接进入阶段4校验生成）
       └─ 未命中 ──► 进入阶段1，按文档自行分析
       │
       ▼
[阶段1] 文档预处理 + 认证类型识别（KEY STEP）
       │  ├─ 格式识别 / 编码统一 / 表格提取
       │  └─ 【认证类型识别】判定属于 OAuth / 短信 / 账号密码
       │
       ▼
[阶段2] 按认证类型分流处理（详见「认证类型专项处理」）
       │  ├─ OAuth：三阶段拆分映射设备 UI 两区块
       │  ├─ 短信：处理 templateContent 必引 + 验证码校验
       │  └─ 账密：标准单步/多步处理
       │
       ▼
[阶段3] 设备能力适配与转换
       │
       ▼
[阶段4] 配置生成与一致性校验
       │
       ▼
     输出结构化配置（认证配置.md）

阶段 0：知识库优先查询

匹配维度（按优先级）：

1. 平台名称 —— 出现在文档标题/正文，如「IDTrust」「一信通」「钉钉 IDaaS」「企业微信」等。
2. 接口 URL 特征 —— 如 /oauth2/authorize、/iam/token、特定短信平台路径。
3. 认证模式特征 —— 授权码模式 / 短信验证码 / 账密登录。

强特征优先判定：文档出现明确平台名或极其特有的参数/路径时，必须判定匹配成功，基于已知标准配置逻辑生成，严禁判失败。

检索顺序（严格逐层判定）：

内置知识库已收录 39 个已脱敏案例（cases/oauth/ 6 个 OAuth 平台、cases/短信/ 33 个短信网关），常见平台的文档大概率能命中，命中后优先复用案例里的配置结构，只替换参数值。

检索命令：用 scripts/search_kb.py 按特征词打分检索，而不是凭印象判断有没有案例。脚本默认同时检索内置与外部知识库，输出标注每条命中来自 [内置] 还是 [外部]。

# 只查内置知识库（未给目录参数时的默认行为）
python scripts/search_kb.py <特征词1> <特征词2> ...

# 同时查内置 + 外部知识库（目录参数写在特征词之前，可给多个）
python scripts/search_kb.py "<知识库目录>" <特征词1> <特征词2> ...

# 查看知识库中有哪些案例
python scripts/search_kb.py --list

特征词取三到五个：平台名 + 接口路径 + 平台特有参数名，例如 IDTrust /oauth2/token client_secret。

知识库为空或未命中属正常状态，不视为错误，按「未命中处理」执行，并在输出中如实注明。用户需要新增案例时：

python scripts/search_kb.py --init "<知识库目录>"     # 生成骨架（cases/ 与 _template.md）

案例文件命名 <平台名>-<认证类型>.md，文件顶部必须写「特征行」（平台名 / 接口路径特征 / 参数特征），检索命中主要靠它。

命中处理：在「文档分析总结」注明 本配置基于知识库已知案例【xxx平台】生成，仅替换差异点。
未命中处理：注明 未找到匹配案例，本配置基于文档分析生成，严格执行阶段 1~4。

阶段 1：文档预处理 + 认证类型识别

文档预处理：用 scripts/read_auth_doc.py 抽取正文与表格。

python scripts/read_auth_doc.py "<认证接口文档路径>"

.docx / .xlsx 走零依赖解析，脚本输出的抬头会标明「抽取到表格 N 个」；.pdf 需要 pdfplumber（缺失时脚本会提示 pip install pdfplumber，或请用户另存为 .docx）。

读取 .doc/.docx 后必须提取表格内容验证关键信息（URL、请求方式、数据格式、参数列表）。如无法完整读取表格（表格数为 0 但文档明显有参数表），必须告知用户，禁止自行推断。

认证类型识别 —— 三类认证的强特征（满足任一即判定）：

{{env.code}} 的语义随类型变化，识别类型后必须明确其含义，避免混淆：

• OAuth 时 = 授权码（设备从回调自动提取）
• 短信时 = 短信验证码（用户输入）

混合场景（如 OAuth + 短信二次验证）按主认证类型处理，并向用户确认。

完整识别规则与各类型专项处理见 references/auth-types.md，OAuth 两区块映射细节见 references/oauth-workflow.md。

阶段 2：按类型分流处理

• OAuth → 三阶段（获取 code → 获取 access_token → 获取用户信息）拆分映射设备 UI 两个配置区块。获取 userinfo 步必须有且仅有一项字段映射为「用户名」。
• 短信 → {{env.templateContent}} 必须被引用（否则模板内容传不到平台）；{{env.code}} 用作验证码校验入参。
• 账号密码 → 标准单步/多步；密码需加密时在自定义请求变量中用 code_util 处理后经 {{env.xxx}} 引用。

阶段 3：设备能力适配

设备仅支持文档列明的库与工具函数，禁止伪造 API。已内置 crypto，禁止出现 const crypto = require('crypto') 之类的 require 代码。不确定设备是否支持某功能时，明确标注，而非写伪代码。

库清单、变量规范、code_util 函数表与脚本函数签名见 references/device-spec.md。

需要写「自定义请求变量」或「响应预处理」脚本时，先查 references/code-snippets/README.md 索引挑现成模板（时间戳、编码、MD5/SHA/HMAC、AES/DES/RSA、SM2/SM3/SM4、响应取值等），再按文档改参数，不要凭空撰写加密与签名代码。模板中的 xxxxxx / xxxxx 为需平台提供的定值，必须替换；算法名要与密钥长度匹配（aes-128 = 16 字节、aes-256 = 32 字节、sm4 = 16 字节）。

阶段 4：配置生成与一致性校验

生成前逐项核对 references/rules-and-checklist.md 中的「关键配置校验清单」，重点：

• 认证类型已明确判定；
• 请求参数与请求体不重复列同一参数；
• 脚本中定义的 env.xxx 都被 {{env.xxx}} 引用，无「定义未使用」；
• 标注「需平台提供」的项都在配置或脚本中被使用；
• 每一步请求都配置了认证成功条件（多步请求的强制要求，否则设备无法执行下一步）。

输出要求

输出一个 markdown 文件（如 认证配置.md）：

• 仅输出配置内容，不添加额外的说明文档、版本信息、常见问题等。
• 文档最前面必须有「文档分析总结」。
• 按识别出的认证类型选择对应模板输出，不要输出回执查询、上行短信接收、登出等非认证必需接口。

「文档分析总结」必须包含：认证类型及判定依据、知识库匹配情况、文档明确的关键信息、变量依赖关系说明、需平台提供的信息（用 xxxxx 代替的项逐条列出）、缺失或需核实的信息。

三套输出模板见 references/output-templates.md。

用户输入示例

请按照工作目录中 xxx 接口文档帮我生成 aTrust 认证对接配置
知识库目录在 D:\xxx，请先查询是否有【xxx平台】的已知案例，没有再分析文档生成
这是一份 OAuth 单点登录文档，帮我生成对接配置

资源

scripts/

• read_auth_doc.py —— 抽取认证接口文档的正文与表格（docx 走零依赖 XML 解析，pdf 走可选库，md/txt/html/csv 直接读）。
• search_kb.py —— 按特征词对知识库打分检索，输出候选案例、命中原因与命中片段。默认同时检索内置与外部知识库；--init "<目录>" 生成外部知识库骨架；--no-builtin 只查外部；--list 列出案例。
• import_kb.py —— 把已有的案例文档批量整理为知识库格式：按规则脱敏（内网图片、署名行、裸 IP、长密钥、疑似口令）并自动提取特征行。只读源目录。支持 --dry-run、--redact-terms-file、--rename-map。
• import_snippets.py —— 把设备脚本片段库按主题合并为 references/code-snippets/ 下的模板文档，复用 import_kb.py 的脱敏规则，并对原文笔误、示例参数不匹配等问题就地加提示。只读源目录。支持 --dry-run。

knowledge-base/

内置知识库，随技能分发，已收录 39 个已脱敏案例。

• README.md —— 三层知识来源与优先级、外部知识库位置建议、案例命名规范、脱敏红线。
• _template.md —— 案例条目模板，新增案例时复制填写（顶部「特征行」为必填）。
• cases/oauth/ —— 6 个 OAuth 2.0 平台案例（IDTrust、UniTrust、派拉、竹云、阿里云 IDaaS、飞书）。
• cases/短信/ —— 33 个短信网关案例（阿里云、腾讯云、华为云、火山引擎、移动云 MAS、梦网、云片等）。
• _scaffold/ —— --init 生成外部知识库时复制的骨架，不参与检索。

> ⚠️ 本目录会被打进 zip 并提交到公开技能广场，只允许放已脱敏、可公开的案例（无真实密钥、域名、IP、账号）。
> 客户真实案例请放在技能目录之外的外部知识库，用 python scripts/search_kb.py --init "<目录>" 生成。

references/

• device-spec.md —— 设备配置项总览、user/config/env/response/result 变量规范、脚本函数签名、可用库与 code_util 工具函数。
• auth-types.md —— 三类认证的完整识别特征、短信与账密专项处理规则。
• oauth-workflow.md —— OAuth 两区块映射表、state 参数处理原则、变量流向链路、响应预处理标准模板。
• output-templates.md —— 输出格式模板 A（OAuth）/ B（短信）/ C（账号密码）。
• rules-and-checklist.md —— 通用强制规则（信息优先级、参数与体区分、变量一致性校验、需平台提供值规范）与关键配置校验清单。
• code-snippets/README.md —— 脚本模板索引：按需求找现成代码（时间戳/编码/哈希与 HMAC/AES/DES/RSA/国密/响应取值），含占位符、密钥长度与输出编码的使用规则。
• code-snippets/自定义请求变量/ —— 7 个主题模板：时间戳与随机值、编码转换、哈希与 HMAC 签名、对称加密 AES、对称加密 DES、非对称加密 RSA、国密算法 SM2/SM3/SM4。
• code-snippets/响应预处理/ —— 响应取值与万能脚本（兜底）、结构化数据处理（JSON 字符串/数组/纯数字）。