技术方案多视角评估

功能概述

• 对输入的技术方案文档进行多端格式解析（PDF/Markdown/飞书），并结合 PRD 作为需求对照佐证技术方案覆盖度。
• 基于四个视角（产品、后端研发、前端研发、测试/QA）的 评分标准 逐项评分。
• 自动统计各视角得分、等级，并总结跨视角风险、依赖与改进项。
• 生成结构化 Markdown 报告并保存为 TECHPLAN_评估报告_<YYYYMMDD>_<HHMMSS>.md。

系统上下文要求

• 执行顺序：遵循“Step0 加载通用规则 → Step1 加载本技能 Prompt → Step2 执行任务 → Step3 输出完整产物”流程，确认基础规则后方可进入技能逻辑。
• 语言协议：思考与回复全程使用简体中文，除代码/专有名词外不得夹杂其他语言，避免翻译腔。
• 思考模式：每个阶段均需显式经历“理解 → 上下文检索 → 规划 → 反思”，确保决策有据可追溯。
• 输入完整性：在实际评审前，必须完成输入清单核验（全量枚举目录、章节），并结合分批读取策略确认所有内容已覆盖。
• 输出规范：中间过程与最终报告均采用结构化 Markdown，呈现思考过程、进度条、完整性声明。
• 分批策略：遇到大文件或长任务，必须分批读取/处理/写入，记录进度并在整合阶段执行完整性验证，禁止省略或压缩信息。

输入清单核验与对账（强制）

• 任意目录或多文件输入，先使用 list_dir 全量枚举，生成“输入目录完整枚举”表，严禁主观筛选。
• 为全部输入项建立追踪表（⬜ 待分析 / ✅ 已完成），读取结束后输出“读取完成对账”并确认覆盖率 100%。
• 若发现遗漏，立即补读并更新对账，确保“输入完整性检查清单”与产出章节一一映射。

分块处理与进度追踪

• 当技术方案或 PRD 超过 3000 字或包含 5+ 大模块时，需制定“分块处理计划”，记录范围、预期产出、状态。
• 执行遵循“分批执行 → 整合汇总 → 完整性验证”三步，逐批更新进度条（█/░）并注明阶段切换。
• 分批处理完成后必须生成最终合并产物，并依据“分批写入完成检查”“输出进度追踪”模板确认内容齐备。

完整性声明与输出校验

• 全量分析结束后，输出“输入完整性声明”，列出输入总数、覆盖率、遗漏项及分块信息。
• 报告写入前后均需自检：章节齐全、表格无截断、得分计算可复核，并引用原文证据。

文档获取

• 技术方案（PDF/Markdown/本地文件）：使用 read_file 或 OCR 方案完整读取，是评分主体。
• PRD（PDF/Markdown/飞书）：使用 read_file 或 OCR 方案完整读取，定位为校验资料，用于确认技术方案覆盖 PRD 需求与场景；引用证据时需说明来源（技术方案或 PRD）。
• 飞书链接：
  1. 识别 URL（https://*.feishu.cn/docx/* / https://*.feishu.cn/wiki/*）。
  2. 执行 feishu2md download --output ./output_md/ <URL>。
  3. 若提示 Authentication token expired，运行 feishu2md auth 重新授权后再下载。
  4. 下载完成后读取生成的 Markdown。

使用流程

业务线选择（强制）

在与用户开始交互时，必须首先询问业务线，必须使用以下单选可交互的方式让用户选择：

请选择业务线（使用 ↑/↓ 箭头导航，空格键确认）：

国际销售客户 国际销售合同 国际销售价格 国际销售订单 国际渠道PSI 国际分销模块 国际销售激励返利 印度销售 印度零售 国际渠道零售

操作说明：

• 使用 ↑/↓ 箭头键在选项间导航
• 使用空格键确认当前选中的选项
• 按 Enter 键完成选择

重要：

• 只有在用户明确选择业务线后，才能继续进行后续的技术方案评估流程
• 选择结果需要记录在评估报告的基本信息部分
• 当前选中的选项会高亮显示

严禁操作：

• 绝对禁止将本技能的 references/ 目录下任何文件拷贝到项目工作目录。
• 绝对禁止在用户项目目录下创建这些文件的副本或缓存。
• 如需阅读文件内容，请使用 read_file 工具直接读取技能基础路径下的原始文件。

重要: 本技能的评分标准文件位于技能基础路径的 references/ 子目录下。在读取这些文件时，必须使用技能基础路径的绝对路径（通过 SKILL.md 文件所在目录确定）拼接 references/ 子目录，而非当前工作目录的相对路径。

获取技能基础路径的方法：

• 技能基础路径 = SKILL.md 文件所在的目录路径
• 评分标准文件路径 = {技能基础路径}/references/{评分标准文件名}

1. 收集上下文：必须通读技术方案全文，记录版本、范围、依赖、风险，并同步读取 PRD 用于需求对照。超长文档需分章节阅读并做摘要，但每个章节都要覆盖，不能只凭局部摘要进行评审。必要时拆分章节并建立索引，确保有证据指向原文位置。
2. 按视角评分：依次遍历评分标准，针对技术方案证据判定条目评分。
   • 说明中需引用章节、链接或附件编号。
   • 条目状态：每个 评分标准 条目都要同步记录 状态 = ✅ 通过 / ⚠️ 待补充 / ❌ 未通过，并在最终报告中逐条输出。
3. 记录问题：对 raw_score < 满分 的条目记录问题、影响、建议，可按视角或主题聚合。
4. 统计得分：
   • 视角加权得分：对每个条目求和，得到该视角的总得分。
   • 视角标准化：每个视角的展示分数与满分严格按照评分标准给出的分数计算。
   • 全局得分固定 100 分： 全局得分固定100分。
5. 汇总洞察：提炼跨视角共性风险（如技术方案与 PRD 不符、依赖同步缺口、交付排期冲突等）并按优先级排序。
6. 输出报告：使用模板撰写 Markdown 并 write_file 保存，确保包含输入完整性、分块计划、得分概览、各视角详情、改进建议等内容。

稳定输出守则

• 四类强制输出：输入目录完整枚举表、读取完成对账表、分块处理计划表、视角得分概览表必须全部出现且顺序固定；缺任意表格需立即停止并补齐。
• 评分明细 完整展开：每个视角的 P0、P1 条目均须逐条呈现；若无证据信息也需以 ❌ 或 ⚠️ 记录，不得省略或合并条目。
• 章节映射一致：条目“证据”列必须落到原文章节/页码/段落 ID，确保可溯源；若来自 PRD 需标记来源。
• 失败防护：生成报告前需二次检查“条目追踪表”与输出表格行数一致；发现缺口必须回到对应 评分标准 重评，不得跳过。

报告生成自检清单

大文件分批读取策略

触发条件:
  文件行数: ">1000行"
  文件大小: ">50KB"

分批读取规则:
  1. 首次读取: read_file(offset=1, limit=500) → 了解结构
  2. 后续读取: 按需读取特定范围，或分批读取全部
  3. 禁止行为: 仅读取开头就假设后续内容

读取完整性检查:
  - 确认已读取文件全部行数（通过 full_length 字段）
  - 如未读完，必须继续读取或说明原因

三步处理流程（强制）

┌─────────────────────────────────────────────────────┐
│ Step 1: 分批执行                                     │
│ - 大文件分批读取                                     │
│ - 大任务分批处理                                     │
│ - 大输出分批写入                                     │
│ - 每批独立完成，记录进度                             │
└─────────────────┬───────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────────────────┐
│ Step 2: 整合汇总                                     │
│ - 收集所有分批结果                                   │
│ - 去重与合并                                        │
│ - 处理跨批次依赖                                     │
└─────────────────┬───────────────────────────────────┘
                  ↓
┌─────────────────────────────────────────────────────┐
│ Step 3: 完整性验证                                   │
│ - 核对输入项全部覆盖                                 │
│ - 核对输出项无遗漏                                   │
│ - 输出完整性声明                                     │
└─────────────────────────────────────────────────────┘

禁止的读取行为

❌ 绝对禁止：
1. 仅读取文件开头就假设后续内容。
2. 凭记忆或假设文件内容，不实际读取。
3. 跳过“非重点”章节不读取。
4. 因文件过长而只读取部分。
5. 忽略工具返回的完整信息。

✅ 正确做法：
1. 大文件分批读取，确保覆盖全部内容。
2. 每次读取记录已读范围与剩余范围。
3. 所有章节客观读取，不主观筛选。
4. 读取完成后确认 full_length 全覆盖。

评分清单与标准

评分说明

• 评分标准：采用 100 分制，各考核项有明确的分值分配，按实际完成情况打分。
• 每个考核项根据评分标准中的描述进行打分，满分即为该考核项的分值。

评分标准 引用（逐视角维护）

所有 评分标准 文件位于 {技能基础路径}/references/ 目录。使用时需先获取技能基础路径（即 SKILL.md 文件所在目录），然后拼接子路径：

• 评分标准：{技能基础路径}/references/后端技术方案综合评分标准（100分制）.md

使用说明：

1. 打开对应 评分标准，按章节（如“需求与范围对齐（P0）”等）依次评估。
2. 在记录表中登记每条目的 raw_score / 证据 / 责任人 / 建议。
3. 评分标准 更新时直接编辑上述文件；技能读取最新内容，无需再修改 SKILL.md。

汇总与输出

评分聚合

• 报告中汇总每个视角的 得分（0-100） / 满分（100） / 等级。
• 视角得分低于 0.6*满分 时，至少列出 2 条高优问题及责任建议。
• 提供“优先改进项 Top 3”，含影响、责任人、截止时间。
• 评分标准 逐条输出：每个视角需附“条目级打分表”，列出 评分标准 每一项的 条目名称 / 证据 / score / 状态(✅/⚠️/❌)，确保通过/未通过/待补充全部可追溯；输出时必须按照 P0 / P1 分段展示，P0 优先级表格置顶，其次 P1， P2 优先级不展示明细，严禁混排或省略任意优先级的条目。
• 条目解释要求：每条 评分标准明细 行都要写出“定位 + 证据 + 解释”。定位需具体到章节/页码/段落/原型链接；证据需给出原文摘录或 paraphrase；解释需说明技术方案（或 PRD）如何满足条目。若状态为 ⚠️/❌，必须在解释中追加“问题产生原因 + 影响/缺失信息”，禁止笼统描述或留空备注。

报告结构

# 技术方案多视角评估报告

## 基本信息
- 文档名称：
- 评审时间：
- 评审人：
- 版本/范围：

### 输入目录完整枚举
|序号|输入项|类型|定位|状态|备注|
|---|---|---|---|---|---|
|1|[技术方案]|Markdown / PDF|主评材料|✅|本地 `read_file`，含架构、流程|
|2|[PRD 链接或文件]|飞书 / PDF|校验材料|✅|通过 `feishu_doc` 拉取全文|
|3|...|...|...|...|...|

### 读取完成对账
|输入项|定位|状态|说明|
|---|---|---|---|
|技术方案|主评材料|✅|按章节分批读取，完成 100%|
|PRD|校验材料|✅|单文件，未触发分页，已完整审阅|

### 分块处理计划与进度
|块|范围|预期产出|状态|
|---|---|---|---|
|K1|技术方案 第1-2章 背景、目标|锁定业务目标、约束|✅|
|K2|技术方案 架构&流程|梳理链路、模块、异常|✅|
|K3|技术方案 数据、接口、发布|列出依赖、容量、运维策略|✅|
|K4|PRD 对照章节|确认需求覆盖与例外|✅|

进度：██████████ 100%

## 视角得分概览
|视角|得分|满分|等级|
|----|----|----|------|----|
|产品|XX|100|良好|
|后端|XX|100|优秀|
|前端|XX|100|一般|
|测试/QA|XX|100|风险|
|**全局（0-100）**|XX|100|XX|

> 全局得分 = (Σ视角得分) ，用同一等级表判定整体质量。

## 视角详情
### 产品视角
- **亮点**：
- **主要问题**：逐条使用 `位置（章节/页码/表单 ID） + 原文摘录或 paraphrase + 具体冲突/缺口 + 影响` 格式描述，如 `3.3 规则配置允许多选，但 3.4 明细逻辑限制单选 → 交互冲突，需统一`。
- **建议**：指出需补齐的字段/性能/同步/依赖信息，并写明期望提供者与截止时间。
- **条目级打分**：

| 条目 | 证据 | score | 状态 | 定位说明 |
|------|------|-------|------|-----------|
| 产品-1 用户价值 | 技术方案 第2章 | 2 | ✅ | `2.1 背景：缺少 ROI 数据` |
| ... | ... | ... | ⚠️ | ... |

> **批注**：证据列需写 `章节/页码/链接`，定位说明列需给出 `原文摘录 + 问题 + 期望补充`，使读者能直接定位 技术方案 原文。


### 后端视角
...

## 高优先级改进项
1. [问题 + 影响 + 责任人 + 截止]
2. ...
3. ...

## 输入完整性声明
- 输入总数：N（技术方案 ×1、PRD ×1、附件 ×k）
- 覆盖率：100%
- 分块：与“分块处理计划”一致，无遗漏
- 若存在异常，列出补救策略

所有输出需与输入清单、分块计划、逐条打分表保持一一对应，确保审计可追溯，且明确技术方案为主评材料、PRD 为覆盖校验依据。

文件保存

• 命名：TECHPLAN_评估报告_<YYYYMMDD>_<HHMMSS>.md。
• 保存路径：在用户执行技能时的当前工作目录下的 ./reports/ 子目录中。
• 实现要求：在写入报告前，检查当前工作目录下是否存在 reports 目录，如果不存在则创建该目录。
• 使用 write_file 将完整的 Markdown 报告写入保存路径中。

评估报告提交

• 调用时机：在生成评估报告之后必须立即调用，此步骤必须执行，不可遗漏，将评估信息同步至数据库。
• 需要调用脚本, 脚本路径：{技能基础路径}/scripts/submit_tech_score.py（使用技能基础路径的绝对路径），通过命令行方式传给该脚本全部所需参数，将评估信息保存至数据库。
• 重要说明：
  • --url 参数只提供API服务器基础地址（如 http://10.38.219.120:80），脚本会自动拼接完整路径 /fullstack/api/tech_plan/score/submit
  • 不要在 --url 参数中包含完整路径，否则会导致URL重复
  • 优先使用 python3 命令调用脚本。如果系统中 python3 命令不可用，则使用 python 命令替代。执行前可先检测命令可用性，选择合适的命令执行脚本。
• 调用示例：

python3 {技能基础路径}/scripts/submit_tech_score.py --url http://10.38.219.120:80 \
    --tech-doc-name "<技术文档名称>" \
    --tech-doc-link "<技术文档链接>" \
    --submitter "<提交人>" \
    --business-line "<业务线>" \
    --product-score <产品视角评分> \
    --backend-score <后端视角评分> \
    --frontend-score <前端视角评分> \
    --test-score <测试视角评分> \
    --global-score <全局总分> \
    --global-level "<全局等级>"

• 参数说明：
  • --url：API服务器基础地址（必填，例如：http://10.38.219.120:80），脚本会自动拼接 /fullstack/api/tech_plan/score/submit
  • --tech-doc-name：从技术方案文件名或报告”基本信息”部分提取
  • --tech-doc-link：用户提供或文档中的链接（如飞书 URL），非必填项，只有当用户传入飞书文档时才有链接地址，对于 md 或 pdf 格式的文件该参数传空字符串
  • --submitter：评审人（从报告”基本信息”获取）
  • --business-line：业务线（从用户选择的业务线获取，必填字段）
  • --product-score：产品视角得分（0-100）
  • --backend-score：后端视角得分（0-100）
  • --frontend-score：前端视角得分（0-100）
  • --test-score：测试/QA视角得分（0-100）
  • --global-score：全局总分（0-100）
  • --global-level：等级（优秀/良好/一般/风险）
• 错误处理：脚本执行失败时需明确告知用户失败原因和解决建议，打印完整的错误信息，不影响报告生成和主流程。
• 完整接口地址：http://10.38.219.120:80/fullstack/api/tech_plan/score/submit（由脚本自动拼接）