技术方案多视角评估
功能概述
- 对输入的技术方案文档进行多端格式解析（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）。 - 飞书链接：
- 识别 URL（
https://*.feishu.cn/docx/*/https://*.feishu.cn/wiki/*）。 - 执行
feishu2md download --output ./output_md/ <URL>。 - 若提示
Authentication token expired，运行feishu2md auth重新授权后再下载。 - 下载完成后读取生成的 Markdown。
- 识别 URL（
使用流程
业务线选择（强制）
在与用户开始交互时，必须首先询问业务线，必须使用以下单选可交互的方式让用户选择：
请选择业务线（使用 ↑/↓ 箭头导航，空格键确认）：
国际销售客户 国际销售合同 国际销售价格 国际销售订单 国际渠道PSI 国际分销模块 国际销售激励返利 印度销售 印度零售 国际渠道零售
操作说明：
- 使用 ↑/↓ 箭头键在选项间导航
- 使用空格键确认当前选中的选项
- 按 Enter 键完成选择
重要：
- 只有在用户明确选择业务线后，才能继续进行后续的技术方案评估流程
- 选择结果需要记录在评估报告的基本信息部分
- 当前选中的选项会高亮显示
严禁操作：
- 绝对禁止将本技能的
references/目录下任何文件拷贝到项目工作目录。 - 绝对禁止在用户项目目录下创建这些文件的副本或缓存。
- 如需阅读文件内容，请使用
read_file工具直接读取技能基础路径下的原始文件。
重要: 本技能的评分标准文件位于技能基础路径的 references/ 子目录下。在读取这些文件时，必须使用技能基础路径的绝对路径（通过 SKILL.md 文件所在目录确定）拼接 references/ 子目录，而非当前工作目录的相对路径。
获取技能基础路径的方法：
- 技能基础路径 =
SKILL.md文件所在的目录路径 - 评分标准文件路径 =
{技能基础路径}/references/{评分标准文件名}
- 收集上下文：必须通读技术方案全文，记录版本、范围、依赖、风险，并同步读取 PRD 用于需求对照。超长文档需分章节阅读并做摘要，但每个章节都要覆盖，不能只凭局部摘要进行评审。必要时拆分章节并建立索引，确保有证据指向原文位置。
- 按视角评分：依次遍历评分标准，针对技术方案证据判定条目评分。
- 说明中需引用章节、链接或附件编号。
- 条目状态：每个 评分标准 条目都要同步记录
状态 = ✅ 通过 / ⚠️ 待补充 / ❌ 未通过，并在最终报告中逐条输出。
- 记录问题：对
raw_score < 满分的条目记录问题、影响、建议，可按视角或主题聚合。 - 统计得分：
- 视角加权得分：对每个条目求和，得到该视角的总得分。
- 视角标准化：每个视角的展示分数与满分严格按照评分标准给出的分数计算。
- 全局得分固定 100 分： 全局得分固定100分。
- 汇总洞察：提炼跨视角共性风险（如技术方案与 PRD 不符、依赖同步缺口、交付排期冲突等）并按优先级排序。
- 输出报告：使用模板撰写 Markdown 并
write_file保存，确保包含输入完整性、分块计划、得分概览、各视角详情、改进建议等内容。
稳定输出守则
- 四类强制输出：输入目录完整枚举表、读取完成对账表、分块处理计划表、视角得分概览表必须全部出现且顺序固定；缺任意表格需立即停止并补齐。
- 评分明细 完整展开：每个视角的 P0、P1 条目均须逐条呈现；若无证据信息也需以
❌或⚠️记录，不得省略或合并条目。 - 章节映射一致：条目“证据”列必须落到原文章节/页码/段落 ID，确保可溯源；若来自 PRD 需标记来源。
- 失败防护：生成报告前需二次检查“条目追踪表”与输出表格行数一致；发现缺口必须回到对应 评分标准 重评，不得跳过。
报告生成自检清单
| 序号 | 检查项 | 说明 |
|---|---|---|
| 1 | 输入清单 | 确认“输入目录完整枚举”“读取完成对账”两表均存在且状态列为 100% |
| 2 | 分块计划 | 分块处理计划行数 ≥1，进度条与计划状态一致 |
| 3 | 评分标准表 | 每个视角均出现 P0、P1 两张表；无 P0/P1 亦需输出空表声明 |
| 4 | 评分公式 | 视角得分=明细得分求和；全局得分=视角得分平均值 |
| 5 | 问题&建议 | raw_score<满分 的条目在“主要问题/建议”中有对应记录 |
| 6 | 完整性声明 | 末尾“输入完整性声明”列出输入数量、覆盖率、分块映射 |
大文件分批读取策略
触发条件:
文件行数: ">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
使用说明：
- 打开对应 评分标准，按章节（如“需求与范围对齐（P0）”等）依次评估。
- 在记录表中登记每条目的
raw_score / 证据 / 责任人 / 建议。 - 评分标准 更新时直接编辑上述文件；技能读取最新内容，无需再修改
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（由脚本自动拼接）