Eliteforge Tech Doc

EliteForge Tech Doc

目标

• 基于已有材料生成可评审技术设计文档，不凭空编造事实。
• 覆盖当前执行目录中的全部文档与图：至少纳入来源清单并给出处置结论（已采纳/背景参考/待确认）。
• 优先复用仓库中的既有术语、流程名称和图示风格。

执行顺序（每次都做）

1. 在当前执行目录运行 scripts/list_doc_and_diagram_sources.sh . 盘点资料。 2. 建立“来源清单”并按优先级读取：

• P0：README*、*design*、*architecture*、*spec*、docs/** 中核心文档。
• P1：接口、数据模型、部署、运维、故障处理文档。
• P2：长尾说明文档与图像资源（至少做一行摘要，不遗漏）。

3. 建立事实依据（建议字段：结论、证据文件、置信度、备注）。 4. 先读 references/tech-doc-template.md，按模板起草目标文档。 5. 优先复用已有图：

• 存在 .mmd/.mermaid/.puml/.plantuml/.drawio 时，优先引用或改写为同等语义图块。
• 仅存在图片图（.png/.jpg/.jpeg/.webp）时，只能依据周边文档和文件名归纳，不确定项标记为“待人工确认”。

6. 输出文档到用户指定路径；用户未指定时默认写入当前目录 ./tech-design.md。 7. 按 references/quality-checklist.md 自检后再回复结果。

强制约束

• 禁止臆造组件、接口、流程、状态、时序关系。
• 每个关键结论至少绑定 1 个来源文件路径。
• 发现冲突信息时，必须显式列出冲突点与取舍依据。
• 不得忽略扫描结果中的任何文档/图文件；无法消费的文件必须写明原因。
• 输出文档必须包含“来源清单”和“待确认项”。
• 涉及插件化、SPI、Hook等可扩展设计时，必须包含“模块扩展点设计”章节，内部接口设计不属于可扩展范围。

图与流程提炼规则

1. 对流程类内容，优先输出“场景化结构”：触发条件、输入、步骤、输出、异常分支。 2. 对调用链内容，优先使用 mermaid sequenceDiagram 表达关键参与者与调用方向。 3. 对状态流转内容，优先使用 mermaid stateDiagram-v2 表达状态与迁移条件。 4. 对伪代码，保留领域动作名，不替换为空泛描述。 5. 对无法确认的图含义，保留原文件路径并标注“待人工确认”，不要猜测细节。

产出文档最低结构

按模板输出，至少包含以下章节：

1. 文档来源清单 2. 背景与目标 3. 术语与边界 4. 核心场景流程（含伪代码） 5. 时序图 6. 状态图 7. 模块扩展点设计（无扩展时写“暂不支持扩展。”，但不能省略标题） 8. 风险与待确认项

便于从业务动作追溯到系统实现。

输出风格

• 默认中文输出，关键名词沿用原文（如模块名、接口名、类名）。
• 段落短句化，避免泛化空话。
• 图和伪代码只保留对评审决策有价值的内容，避免冗长重复。

参考资料读取策略

• 首次执行先读 references/tech-doc-template.md。
• 出稿前必读 references/quality-checklist.md 做最终检查。

快速命令

# 1) 盘点当前目录文档和图
skills/eliteforge-tech-doc/scripts/list_doc_and_diagram_sources.sh .

# 2) 生成技术设计文档（文件名可改）
# 输出示例：./tech-design-summary.md

示例触发语句

• “请扫描当前目录所有文档和图，产出技术设计文档。”
• “根据仓库里的 markdown 和时序图，整理一份方案设计稿。”
• “把现有设计资料汇总成可评审的 tech design，并标出缺失信息。”

参考文件

• 技术设计文档模板
• 质量自检清单

质量自检清单

在输出技术设计文档前逐条确认：

• [ ] 已执行 list_doc_and_diagram_sources.sh，并覆盖扫描到的全部文档与图。
• [ ] 文档中包含“来源清单”，且每项标注采纳方式。
• [ ] 每个关键结论至少有一个来源文件路径。
• [ ] 流程描述、伪代码、时序图三者语义一致，无互相冲突。
• [ ] 状态图状态与迁移条件可在来源资料中找到证据。
• [ ] 存在插件化/SPI/Hook扩展时，已补“模块扩展点设计”章节
• [ ] 发现冲突信息时已记录取舍依据，不直接忽略。
• [ ] 不确定信息已标记“待确认”，未进行猜测性补全。
• [ ] 输出文件路径明确，且内容结构完整可评审。

技术设计文档模板（通用）

按下面结构组织输出，章节可增删，但不得删除“来源清单”和“待确认项”。

1. 文档来源清单

要求：

• 覆盖扫描到的全部文档与图。
• 对未采纳项写明原因（过期/重复/信息不足等）。

2. 背景与目标

• 当前问题与业务背景
• 本次设计目标
• 明确不在范围内的事项（Out of Scope）

3. 术语与边界

• 核心名词解释
• 系统边界、上下游、依赖关系
• 空间/租户/环境边界（如存在）

4. 核心场景流程（建议场景化）

场景可从：

• 用户与页面的交互进行推导，比如页面数据如何加载出来的、如何新增，更新，删除的等交互场景
• 系统启动时是否有初始化
• 领域内部的一些其他操作

每个场景建议固定模板：

场景 N：{场景名称}

• 触发条件：
• 输入：
• 关键步骤：
• 输出：
• 异常与回滚：
• 证据来源：

如原始资料有伪代码，优先保留并做最小改写：

ServiceA.handle(request):
    data = Repository.load(...)
    Rule.check(data)
    result = Gateway.call(...)
    Repository.save(result)
    return result

5. 时序图

根据场景章节一一对应说明。 优先复用已有时序图；无现成时序图时再基于事实表生成。

sequenceDiagram
    participant A as Client
    participant B as Service
    participant C as Repository
    A->>B: request
    B->>C: query
    C-->>B: data
    B-->>A: response

6. 状态图

用于展示实体或流程状态迁移。

stateDiagram-v2
    [*] --> INIT
    INIT --> RUNNING: start
    RUNNING --> FAILED: error
    RUNNING --> DONE: finish

7. 模块扩展点设计

当方案存在插件化、SPI、Hook、策略模式、脚本扩展时，必须补这一章。

建议用表格描述扩展点：

扩展点使用说明，简要使用伪代码即可。

8. 风险与待确认项

• 风险清单（技术、性能、安全、运维）
• 待确认问题（明确 owner 或建议确认路径）
• 决策记录（如有冲突信息，写明取舍依据）