technical-proposal-expert

中文正式文档写作 skill：技术标书、方案设计报告、测试报告、周报；其余文档走常规兜底。根目录 SKILL.md 是唯一入口，skill 内部把它当作强制指令集执行。

为什么有它

写技术标书和设计报告时，最常见的质量问题是「泛泛而谈」：实现方案只有概念词（微服务、高可用、大数据），没有选型理由、机制细节、指标支撑。本 skill 用三件事解决这个问题：

1. 内置知识库（knowledge/）：按技术域组织的「技术卡片」，写作时按技术点/指标关键词选择性检索，只读取命中章节，节省上下文
2. 项目素材库（写作目录下的 素材库/）：把招标文件摘编、技术规范、历史标书等放进项目目录，写作时全文读取，让内容贴合本项目实事；不设全局素材库，项目写完素材随项目保留或清理
3. 深度写作六问：每个关键技术点必须回答「解决什么问题 / 为什么这么选 / 关键机制与数据流 / 工程化落地 / 如何验证 / 风险与降级」，禁止用修饰词堆砌替代实质内容

再加上零分点（标书正文禁止分点）、禁词表、「待确认」不编造、交付前复核清单等约束，保证输出有格式、有深度、可核验。

安装

把整个仓库克隆到 skills 目录，安装目录名统一为 technical-proposal-expert：

# Cursor
git clone  ~/.cursor/skills/technical-proposal-expert

# Claude Code
git clone  ~/.claude/skills/technical-proposal-expert

每种工具只装一份。旧的 software-engineering-docs 名称已废弃，请删除旧副本，避免列表中出现「两个 skill」。

未自动加载时，在对话里说：使用 technical-proposal-expert 写【文档类型】。

使用流程

1. 说出文档类型 → skill 匹配唯一场景（标书/设计报告/测试报告/周报/兜底）
2. 确认场合与身份（给谁看、谁写），读取对应 references/*.md
3.（可选）在写作项目目录放素材到 素材库/
4. 运行索引脚本（无参数），生成两个 .index.json
5. 写作：按技术点/指标检索 knowledge，用户素材全文读取，按六问展开
6. 交付前复核：待确认清零、禁词扫描、条款响应、指标一致性

直接说要写的文档即可，例如「写技术标书」「出方案设计报告」「写测试报告」「写周报」。类型不明时会先问场景，再读对应 references/。

素材检索（核心用法）

两份内容来源，规则不同：

使用步骤：

1. 在写作项目的工作目录下创建 素材库/（本仓库的 素材库/ 只是模板与说明），放入希望参考的素材（仅 .md / .txt，可建子目录）。建议放：招标文件摘编、技术规范、历史标书、架构说明、通用技术文档。
2. 生成索引（无需任何参数，自动扫描 skill 的 knowledge/ 与「当前工作目录的 素材库/」）：

# 在写作项目目录下，用 skill 脚本的完整路径运行（无参数）
python /scripts/index_materials.py

3. 之后写作时，skill 自动按技术点/指标关键词检索：内置知识读取命中章节，用户素材全文读取。素材有新增/变更时，重新运行一次脚本即可。

规则：

• 项目素材与内置知识冲突时以项目素材为准；内置知识用于补足深度
• 索引只是目录（文件清单 + chunk 行区间 + preview），检索后必须回到源文件读原文，禁止凭索引编造内容
• 交付正文不出现「参考了某文档」痕迹（除非用户要求），但草稿/plan 中保留「素材使用清单」以便核验
• 素材可能含敏感信息，.index.json 已 gitignore，素材文件默认不要提交到公开仓库

目录结构

SKILL.md                          # 唯一入口：铁律、工作流、素材检索、六问、交付复核
references/                       # 场景规范（标书/设计报告/测试报告/周报/兜底）
knowledge/                        # 内置知识库（46 份技术卡片与文档模板，按领域分目录，按需检索）
  00-来源登记.md                   # 全部卡片/模板的来源溯源（URL、日期、适用文档）
  文档模板/                        # GJB 438C-2021 拆分的 20 份文档章节骨架（SRS/SDD/DBDD/STR…）
  合规与标准/                      # 标准引用核对表（标准号/状态/日期，不收录正文）
素材库/                           # 素材库模板与说明（实际素材放在写作项目目录）
scripts/index_materials.py        # 索引脚本，零参数运行
scripts/test_index_materials.py   # 脚本测试（标准库，无第三方依赖）
scripts/split_gjb_templates.py    # GJB 438C 模板拆分工具
examples/                         # 写作示例（浅 vs 深对照）

脚本

索引脚本特性：仅支持 .md / .txt（UTF-8 / GBK）；忽略隐藏文件与其他格式；chunk 带行区间与 preview，便于按需回读；只识别「当前工作目录下的 素材库/」，不存在时不报错、仅生成知识库索引。

扩展知识库

• 新增领域：在 knowledge/ 下建目录（如 knowledge/视频AI/），按八段卡片格式写卡片（格式见 knowledge/README.md），并在 SKILL.md 的技术路由表中补一行关键词映射
• 新增场景文档：在 references/ 下加场景规范，并在 SKILL.md 场景路由表登记
• 其他格式素材：docx/pdf/xlsx 等先转成 md/txt 再放入 素材库/

添加素材后如何生成索引

新增 / 修改 / 删除素材后，需要重新生成索引，skill 才能检索到最新内容。脚本无参数，必须在写作项目的工作目录下运行（脚本只认「当前工作目录下的 素材库/」）。

# 1. 在写作项目根目录创建 素材库/（首次使用）
mkdir 素材库

# 2. 放入素材（仅 .md / .txt，UTF-8 / GBK 均可，允许子目录）
cp 招标文件摘编.md 素材库/
cp -r 历史标书/ 素材库/

# 3. cd 到项目根目录，用 skill 脚本的完整路径运行（无参数）
python ~/.cursor/skills/technical-proposal-expert/scripts/index_materials.py

成功时终端会打印形如下面两行：

已生成 knowledge/.index.json：N 个文件，M 个块，共 K 字
已生成 素材库/.index.json：N 个文件，M 个块，共 K 字

约束与要点：

• cd 到哪个目录，索引的就是哪个目录的 素材库/；从 skill 根目录运行只索引内置 knowledge/
• 素材目录名固定为中文 素材库/，改名（材料 / 资料）会识别不到
• 仅支持 .md / .txt，其他格式（docx / pdf / xlsx）先转换
• 隐藏文件 / 隐藏目录自动忽略，不用清理
• 当前目录下没有 素材库/ 时不会报错，只生成 knowledge/.index.json 并提示
• 写作时 skill 读取的是已生成的 .index.json，索引不用每次都跑；素材有变更时再跑一次即可
• 想验证脚本本身是否健康：python scripts/test_index_materials.py（标准库，16 项用例）

当前状态与边界

• 知识库已有 46 份内容：20 份 GJB 438C 文档模板 + 26 份技术卡片（微服务 / 云原生 / 大数据 / 物联网 / 测试 / 高可用 / 等保 / 信创 / 数据治理），来源见 knowledge/00-来源登记.md；AI与视频分析 / 低代码与BPM / 移动端 等目录仍待补充卡片
• 素材仅支持 .md / .txt，其他格式先转换