---
name: tech-plan-assessment
description: 对后端技术团队提供的技术方案进行多视角评分与质量评估。支持 PDF、Markdown 和飞书文档格式，从产品、后端、前端、测试四个视角逐项打分，输出总分、各视角得分、问题列表、改进建议和完整评估报告。
---

# 技术方案多视角评估

## 功能概述
- 对输入的技术方案文档进行多端格式解析（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 需标记来源。
- **失败防护**：生成报告前需二次检查“条目追踪表”与输出表格行数一致；发现缺口必须回到对应 评分标准 重评，不得跳过。

### 报告生成自检清单
|序号|检查项|说明|
|---|---|---|
|1|输入清单|确认“输入目录完整枚举”“读取完成对账”两表均存在且状态列为 100%|
|2|分块计划|`分块处理计划`行数 ≥1，进度条与计划状态一致|
|3|评分标准表|每个视角均出现 `P0`、`P1` 两张表；无 P0/P1 亦需输出空表声明|
|4|评分公式|视角得分=明细得分求和；全局得分=视角得分平均值|
|5|问题&建议|raw_score<满分 的条目在“主要问题/建议”中有对应记录|
|6|完整性声明|末尾“输入完整性声明”列出输入数量、覆盖率、分块映射|

### 大文件分批读取策略

```yaml
触发条件:
  文件行数: ">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）如何满足条目。若状态为 ⚠️/❌，必须在解释中追加“问题产生原因 + 影响/缺失信息”，禁止笼统描述或留空备注。

### 报告结构
```markdown
# 技术方案多视角评估报告

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

### 输入目录完整枚举
|序号|输入项|类型|定位|状态|备注|
|---|---|---|---|---|---|
|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` 命令替代。执行前可先检测命令可用性，选择合适的命令执行脚本。
- 调用示例：
```bash
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`（由脚本自动拼接）