1，LangChain

1.1，构建 Chain Demo

【简单 Chat 演示】LangChain 是一个基于大型语言模型（LLM）开发应用程序的框架，简化了LLM应用程序的开发、生产和部署过程。

import os
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage

os.environ["TOGETHER_API_KEY"] = "sk-***"

model = ChatOpenAI(
    base_url="https://api.deepseek.com",
    api_key=os.environ["TOGETHER_API_KEY"],
    model="deepseek-chat",)

messages = [
    SystemMessage(content="Translate the following from English into Chinese"),
    HumanMessage(content="How are you?"),
]
# 返回 AIMessage 对象
response = model(messages)
print(response.content)

【输出解析器】模型的响应是一个 AIMessage，包含一个字符串响应以及有关响应的其他元数据。

from langchain_core.output_parsers import StrOutputParser
parser = StrOutputParser()
result = model.invoke(messages)
print(parser.invoke(result))

或采用【链条】

chain = model | parser
print(chain.invoke(messages))

1.2，提示词模板

【提示词模板】PromptTemplates 是 LangChain 中用于管理和构建提示词（prompt）的工具，它的作用是把固定文本和变量结合起来，方便动态生成模型输入。

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI

system_template = "Translate the following into {language}:"

prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)
model = ChatOpenAI(
    base_url="https://api.deepseek.com",
    api_key="sk-****",
    model="deepseek-chat")
parser = StrOutputParser()
# 将 prompt 模板、模型 和 输出解析器 串联成一个 chain
# chain 会依次执行：生成提示 → 调用模型 → 解析输出
chain = prompt_template | model | parser
print(chain.invoke({"language": "Chinese", "text": "hi"}))

【指定输出类型】 LangChain 输出结构化的数据，解析为类的实例。

from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field


# 定义输出类
class TranslationResult(BaseModel):
    """翻译结果的结构化输出类"""
    translated_text: str = Field(description="翻译后的文本")
    source_language: str = Field(description="源语言")
    target_language: str = Field(description="目标语言")


# 创建解析器，指定输出为 TranslationResult 类
parser = PydanticOutputParser(pydantic_object=TranslationResult)

system_template = """Translate the following into {language}.

{format_instructions}"""

prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

model = ChatOpenAI(
    base_url="https://api.deepseek.com",
    api_key="sk-***",
    model="deepseek-chat"
)

chain = prompt_template | model | parser

result = chain.invoke({
    "language": "Chinese",
    "text": "Stay curious, and the world will always feel new.",
    "format_instructions": parser.get_format_instructions()
})

print(f"翻译结果: {result.translated_text}")
print(f"源语言: {result.source_language}")
print(f"目标语言: {result.target_language}")

1.3， 流式传输

在LLM生成回复时，不必等待完整结果返回，而是边生成边输出，让用户实时看到生成进度。

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from pydantic import BaseModel, Field

class TranslationResult(BaseModel):
    translated_text: str = Field(description="翻译后的文本")
    source_language: str = Field(description="源语言")
    target_language: str = Field(description="目标语言")


# 创建模型实例
model = ChatOpenAI(
    base_url="https://api.deepseek.com",
    api_key="sk-***",
    model="deepseek-chat",
    streaming=True
)

simple_template = "Translate the following into {language}:"
simple_prompt = ChatPromptTemplate.from_messages(
    [("system", simple_template), ("user", "{text}")]
)

stream_chain = simple_prompt | model | StrOutputParser()

print("翻译中: ", end="", flush=True)
for chunk in stream_chain.stream({
    "language": "Chinese",
    "text": "Stay curious, and the world will always feel new."
}):
    print(chunk, end="", flush=True)
print("\n")

2，Spec-kit

规范驱动开发颠覆了传统的软件开发模式。几十年来，代码至上——规范仅仅是搭建的框架，一旦开始“真正的”编码工作，规范就会被弃之不用。规范驱动开发改变了这一切：规范变得可执行，能够直接生成可运行的实现，而不仅仅是指导实现。

痛点	传统 AI 开发	使用 Spec-Kit 之后
需求偏差	依赖临时提示词，结果常错	由规范定义目标，AI 精准执行
返工频繁	缺乏一致性，代码难维护	有结构的计划与分析流程
协作混乱	各自为战，风格不一	共用章程与统一原则
项目上下文丢失	对话结束上下文消失	规范文件长期存在
变更代价高	改需求要重写 prompt	改 spec → 自动更新后续步骤

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git

2.1，解决痛点

AI 会写代码，但不懂你的“意图”；Spec-Kit 让 AI 理解“要做什么”，而不仅仅是“怎么写”。

【AI生成代码偏离需求】传统 AI 编码助手（如 Copilot、Claude Code）只基于局部上下文或提示词生成代码。

• 功能跑偏、与真实需求不符

• 结构混乱、难以维护

• 缺乏全局一致性

你让 AI “写一个用户登录系统”，它也许能写出登录表单，但不知道你需要安全策略、OAuth 支持、或企业单点登录集成。

【Spec-Kit】通过“规范驱动（spec-driven）”流程，先定义需求规范（spec），再生成计划（plan）与任务（tasks），让 AI 基于完整意图模型（Intent Model）而不是片段提示（Prompt）工作。

【AI 开发缺乏结构化流程】

• 每次从零开始对话

• 无标准化的上下文

• 同一个功能被不同人描述出不同版本

• 没有历史追踪和一致性校验

【Spec-Kit】

1️⃣ /speckit.constitution   → 定义项目章程与原则
2️⃣ /speckit.specify        → 定义功能规范（需求）
3️⃣ /speckit.clarify        → AI 提问澄清细节
4️⃣ /speckit.plan           → 自动生成实施计划
5️⃣ /speckit.tasks          → 拆解为任务单元
6️⃣ /speckit.analyze        → 检查一致性
7️⃣ /speckit.implement      → 执行实现

• 所有决策都有依据（spec）

• 所有输出可追溯（plan、tasks）

• 所有改动可复现（update spec → regenerate）

【AI 不具备项目管理意识】

• 传统对话式 AI 没有“长期记忆”或项目上下文。

• 多人协作时，每个成员都要重复描述背景。

• 同一功能的设计、实现、测试缺乏一致性。

【Spec-Kit】

• 每个项目维护一套结构化规范文件（如 .specify/ 或 .claude/ 目录）。

• AI 可以“读取这些文件”，获得项目上下文。

• 任何人加入项目，都能理解项目意图与决策逻辑。

2.2，命令

【场景命令】

场景	推荐命令
开始新项目	/speckit.constitution
开发新功能	/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement
需求不清楚	/speckit.clarify
担心质量	/speckit.analyze + /speckit.checklist
快速原型	/speckit.specify → /speckit.implement（跳过中间步骤）
团队协作	完整流程（所有命令）

【核心工作流】

阶段	命令	用途
1️⃣	/speckit.specify	将功能需求转化为清晰的规范文档
2️⃣	/speckit.plan	制定功能的技术实现方案
3️⃣	/speckit.tasks	将技术方案分解为可执行的任务清单
4️⃣	/speckit.implement	按任务清单逐步实现功能代码

【辅助功能】

命令	用途	使用时机
/speckit.constitution	定义项目的核心原则和开发规范	项目开始时（可选）
/speckit.clarify	解决规范中的模糊和歧义问题	规范化后（可选）
/speckit.analyze	检查规范、计划、任务的一致性	实现前（可选）
/speckit.checklist	生成需求质量验证清单	任何阶段

2.3，核心功能

【步骤①】项目初始化

specify init --here --ai claude

Claude Code 询问权限问题：

claude --dangerously-skip-permissions

【步骤②】Specify 创建功能规范：为要开发的项目提供具体要求，尽可能明确地说明您要构建的内容以及原因，即“做什么”和“为什么”。此时不要专注于技术堆栈。

• 用途：将功能需求转化为清晰的规范文档
• 何时使用：开发新功能的第一步

【输入】

/speckit.specify 新增一个给PPT生成备注的后端接口

【输出】

• spec.md - 功能规范文档
• checklists/requirements.md - 质量检查清单

【步骤③】Plan 制定技术方案：需要提供希望的技术栈、架构和约束条件，AI 会生成全面的技术实现计划。

• 用途：制定功能的技术实现方案
• 何时使用：规范明确后（specify之后）

【输入】

/speckit.plan 使用 Python 的 FastAPI

【输出】

• plan.md - 技术实现计划
• data-model.md - 数据模型
• contracts/ - API 接口定义
• research.md - 技术决策

【步骤④】Tasks 分解任务：将规格和计划分解为可执行任务

• 用途：将技术方案分解为可执行的任务清单
• 何时使用：技术方案完成后（plan之后）

【输入】

/speckit.tasks

【输出】

• tasks.md - 详细任务清单

【步骤⑤】Implement 实现任务：根据计划执行所有任务

• 用途：按任务清单逐步实现功能代码
• 何时使用：所有准备工作完成后

【输入】

/speckit.implement

【输出】

• 按阶段执行任务
• 遵循 TDD 原则
• 自动跟踪进度

2.4，辅助功能

【Constitution】项目开始时使用：设定了一些 “不可谈判的” 原则，这些原则会贯穿之后的 /specify、/plan、/tasks、/implement 等阶段，以确保 AI 代理及团队在开发过程中保持一致的方向与标准。

• 用途：定义项目的核心原则和开发规范
• 何时使用：项目开始时（可选）

【输入】

/speckit.constitution

我们的项目遵循：
1. 测试驱动开发（TDD）是强制的
2. 代码必须有详细的文档注释
3. 使用 TypeScript + React

【输出】

• .specify/memory/constitution.md - 项目宪章

【Clarify】Constitution 之后，Plan 阶段之前：澄清规范中不够明确的地方。

• 用途：解决规范中的模糊和歧义问题
• 何时使用：规范化后、规划前（可选）

【输入】

/speckit.clarify

【输出】

• 识别需求中的不明确之处
• 提出结构化问题
• 更新规范文档

【Analyze】Tasks 之后，Implement 阶段之前：跨文档的一致性和覆盖度分析。生成包含问题 ID、分类、严重性、位置、建议的 Markdown 表格；

• 用途：检查规范、计划、任务的一致性
• 何时使用：任务分解后、实现前（可选）

【输入】

/speckit.analyze

【输出】

• 一致性分析报告
• 问题清单和修复建议

【Checklist】任何阶段验证质量：生成需求质量验证清单

• 用途：生成需求质量验证清单
• 何时使用：任何阶段验证质量

【输入】

/speckit.checklist

【输出】

• checklists/[名称].md - 定制化检查清单

3，OpenSpec

3.1，解决痛点

OpenSpec 是一个轻量级的、由规范驱动的框架，专为编码助手（coding agents）和命令行界面（CLIs）设计。它提倡一个“规范驱动开发”的理念，意思是在你和 AI 助手真正开始写代码之前，先把要做的东西通过“规范”给固定下来，确保你和 AI的目标完全一致。与 spec-kit 相比：token 消耗减少，生成文档专精。

#全局安装
npm install -g @fission-ai/openspec@latest

#确认安装
openspec --version

3.2，流程

┌────────────────────┐
│  1. 草拟提案        │  分享意图给 AI
│  (Draft Proposal)  │
└────────┬───────────┘
         │
         ▼
┌────────────────────┐
│  2. 审查对齐        │◄──── 反馈循环 ──────┐
│  (Review & Align)  │                    │
└────────┬───────────┘                    │
         │ 批准计划                        │
         ▼                                │
┌────────────────────┐                    │
│  3. 实施任务        │────────────────────┘
│  (Implement)       │  AI 编写代码
└────────┬───────────┘
         │ 部署变更
         ▼
┌────────────────────┐
│  4. 归档更新        │  合并到 specs/
│  (Archive)         │
└────────────────────┘

• 起草变更提案：定义你希望修改或新增的规范内容。

• 审核与对齐：与 AI 助手反复讨论、完善提案内容，直到所有方达成一致。

• 执行任务：基于已批准的规范，让 AI 编写或协助实现相关代码。

• 归档与更新：将最终变更合并回规范的源文件，保持单一真源（source of truth）。

3.3，核心功能

【初始化】

• 系统会提示您选择任何原生支持的 AI 工具（例如 Claude Code、CodeBuddy、Cursor、OpenCode、Qoder 等）；其他助手始终依赖于共享的AGENTS.md存根。
• OpenSpec 会自动为您选择的工具配置斜杠命令，并且始终AGENTS.md在项目根目录写入一个受管理的交接文件。
• openspec/项目中添加了新的目录结构

【输入】

openspec init

【输出】

ForestFocus-main/
├── AGENTS.md              # AI助手指令
└── openspec/
    ├── AGENTS.md          # OpenSpec工作流说明
    ├── project.md         # 项目信息
    ├── specs/             # 规范文档（当前真实状态）
    └── changes/           # 变更提案（进行中的修改）

【填充项目信息】

1. Populate your project context:
   "Please read openspec/project.md and help me fill it out
    with details about my project, tech stack, and conventions"

2. Create your first change proposal:
   "I want to add [YOUR FEATURE HERE]. Please create an
    OpenSpec change proposal for this feature"

3. Learn the OpenSpec workflow:
   "Please explain the OpenSpec workflow from openspec/AGENTS.md
    and how I should work with you on this project"

• 填充你的项目上下文： “请阅读 openspec/project.md，并帮我填写其中关于我的项目、技术栈和开发规范的详细信息。”
• 创建你的第一个变更提案： “我想添加【你的功能名称】。请为这个功能创建一个 OpenSpec 变更提案。”
• 学习 OpenSpec 工作流程： “请解释 openspec/AGENTS.md 中描述的 OpenSpec 工作流程，并说明我该如何与你在这个项目中协作。”

【输入】

后续所有对话都以中文回复

Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions

【创建变更提案】

【输入】

/openspec:proposal 新增一个给PPT生成备注的后端接口

【输出】

openspec/
  changes/
    add-profile-filters/
      proposal.md
      tasks.md
      specs/
        profile/
           spec.md   ← 这是 delta（变更部分）

• tasks.md：列出实现任务，比如数据库修改、API 修改、前端 UI 修改。
• specs/profile/spec.md：列出新增的规范要求和场景。
• proposal.md：你说明为什么要这个功能、目标是什么。

# 实现任务清单

## 1. 数据模型
- [ ] 1.1 在 `Bean.py` 中创建 `PPTNotesRequest` 类
  - 字段：language（语言）、content（页面内容）、pageKind（页面类型）、style（风格）、stream（流式标志）
  - 使用 Pydantic BaseModel 和 Field 进行验证

## 2. 提示词工程
- [ ] 2.1 在 `prompts.py` 中创建 `get_ppt_notes_prompt()` 函数
  - 设计中文提示词模板，生成详细、口语化的演讲稿
  - 支持不同页面类型（cover/contents/content/transition/end）的差异化生成
  - 支持风格参数（演讲稿/要点/教学）

## 3. API端点实现

# PPT演讲备注生成

## ADDED Requirements

### Requirement: PPT备注生成接口
系统必须（MUST）提供 `/tools/aippt_notes` POST接口，接收PPT页面内容并生成详细、口语化的演讲备注。

#### Scenario: 为内容页生成演讲备注
- **GIVEN** 用户已经生成了一个PPT内容页，包含标题和多个要点
- **WHEN** 用户发送POST请求到 `/tools/aippt_notes`，携带页面内容、语言（中文）、页面类型（content）、风格（演讲稿）
- **THEN** 系统使用LLM生成详细的演讲稿文本
- **AND** 备注内容详细、口语化，适合口头演讲
- **AND** 响应以Server-Sent Events (SSE)流式方式返回
- **AND** 生成的文本为纯文本格式，无Markdown格式

#### Scenario: 为封面页生成演讲备注
- **GIVEN** 用户已经生成了PPT封面页，包含标题和副标题
- **WHEN** 用户发送POST请求，页面类型为"cover"
- **THEN** 系统生成简短的开场白演讲稿
- **AND** 内容包括对主题的介绍和演讲目标

#### Scenario: 处理异常情况
- **GIVEN** 用户发送了请求
- **WHEN** LLM调用失败或超时
- **THEN** 系统在流式响应中返回错误信息
- **AND** 错误信息格式为 `\n[ERROR]: {错误详情}\n`

# Change: 新增PPT演讲备注生成接口

## Why
当前系统支持生成PPT大纲和内容，但缺少为PPT页面生成演讲备注的功能。演讲者需要手动编写每页的演讲稿，增加了准备工作的负担。通过AI自动生成详细、口语化的演讲稿，可以帮助用户快速准备演示材料，提升办公效率。

## What Changes
- 新增 `/tools/aippt_notes` POST接口，接收PPT页面内容并生成演讲备注
- 新增 `PPTNotesRequest` 数据模型，支持语言、页面内容、页面类型、风格等参数
- 新增 `get_ppt_notes_prompt()` 提示词模板函数，生成结构化的演讲稿提示词
- 支持流式输出（SSE），提供实时生成体验
- 生成的备注为纯文本格式，详细且口语化，适合直接用于演讲

## Impact
- **新增capability**: `ppt-notes-generation` - PPT演讲备注生成
- **影响文件**:
  - `main.py` - 新增API端点
  - `Bean.py` - 新增请求模型
  - `prompts.py` - 新增提示词模板
- **依赖**: 复用现有的LLM调用基础设施（config.py中的 `create_llm()`）
- **兼容性**: 无破坏性变更，纯新增功能

【审查修订提案】阅读提案、任务、规范变更，可能提出问题或补充

# 查看活跃的变更
openspec list

 Bash(cd "D:\PyCharmWorkSpace\TianGong" && openspec list)       
  ⎿  Changes:
       add-ppt-notes-generation     0/4 tasks

● 当前有 1个活跃提案：
  - add-ppt-notes-generation - PPT演讲备注生成功能
    - 状态：0/4 任务完成
    - 验证：✅ 已通过严格验证

# 验证提案格式
openspec validate add-ppt-notes-generation

# 查看提案详情
openspec show add-ppt-notes-generation

【输入】

有点复杂，简单些，不要求鉴权这些。

【实施变更】

【输入】

/openspec:apply add-ppt-notes-generation

【效果不好】

Fix：请你把非流式修改为流式

在归档前发现的问题，可以直接修复，不需要走复杂的流程。

【归档变更】当所有任务都完成、测试通过：

/openspec:archive add-ppt-notes-generation

• 将 openspec/changes/add-profile-filters/specs/profile/spec.md 的 delta 内容合并到主规范 openspec/specs/profile/spec.md（也就是系统当前的“真规范”）。
• 将 openspec/changes/add-profile-filters/ 标记为已归档或移到 archive 区。