qiniu · freshspf · Aug 4, 2025 · Aug 4, 2025 · Aug 4, 2025 · Aug 4, 2025
diff --git a/docs/cmd-code.md b/docs/cmd-code.md
@@ -0,0 +1,138 @@
+
+
+# AI-Powered Issue to PR Workflow
+
+## 概述
+该流程通过 GitHub Issue 评论触发，自动创建分支、生成代码修改并提交 PR，全程由 AI 驱动。适用于自动化代码维护场景。
+
+## 流程图
+```mermaid
+graph TD
+    A[Issue Comment Event] --> B[创建工作空间]
+    B --> C[创建Git分支]
+    C --> D[创建初始PR]
+    D --> E[初始化Session]
+    E --> F[调用AI生成代码]
+    F --> G[解析结构化输出]
+    G --> H[更新PR内容]
+    H --> I[提交代码变更]
+```
+
+---
+
+## 详细步骤
+
+### 1. 初始化阶段
+| 步骤 | 操作 | 关键数据 |
+|------|------|----------|
+| 1.1 | 接收 GitHub Issue 评论事件 | `event *github.IssueCommentEvent` |
+| 1.2 | 创建带 AI 模型信息的工作空间 | `ws := CreateWorkspaceFromIssueWithAI()` |
+| 1.3 | 创建并推送 Git 分支 | `CreateBranch(ws)` |
+
+### 2. PR 准备阶段
+| 步骤 | 操作 | 关键方法 |
+|------|------|----------|
+| 2.1 | 创建初始 Pull Request | `CreatePullRequest(ws)` |
+| 2.2 | 建立工作空间映射 | `MoveIssueToPR(ws, prNumber)` |
+| 2.3 | 创建 Session 目录 | `CreateSessionPath()` |
+| 2.4 | 注册工作空间 | `RegisterWorkspace(ws, pr)` |
+
+### 3. AI 交互阶段
+**Prompt 模板：**
+```markdown
+根据Issue修改代码：
+
+标题：{{issue_title}}
+描述：{{issue_body}}
+
+输出格式：
+### 改动摘要
+简要说明改动内容
+
+### 修改内容
+- 列出修改的文件和具体变动
+```
+
+| 关键控制点 | 说明 |
+|------------|------|
+| 重试机制 | `promptWithRetry(ctx, code, prompt, 3)` |
+| 输出解析 | `parseStructuredOutput(aiStr)` |
+
+### 4. PR 内容生成
+**PR Body 结构：**
+```markdown
+### 改动摘要
+{{summary}}
+
+### 修改内容
+{{changes}}
+
+### 测试计划
+{{testPlan}}
+
+---
+<details><summary>AI 完整输出</summary>
+{{raw_ai_output}}
+</details>
+
+<details><summary>原始 Prompt</summary>
+{{original_prompt}}
+</details>
+```
+
+### 5. 代码提交阶段
+| 操作 | 方法 | 错误处理 |
+|------|------|----------|
+| 提交变更 | `CommitAndPush(ws, result, code)` | 自动回滚分支 |
+| 最终状态 | 更新 PR URL 到日志 | `pr.GetHTMLURL()` |
+
+---
+
+## 数据结构
+### Workspace 关键字段
+```go
+type Workspace struct {
+    Path        string       // 工作目录路径
+    Branch      string       // Git 分支名
+    AIModel     string       // 使用的AI模型标识
+    PRNumber    int          // 关联的PR编号
+    SessionPath string       // Session存储路径
+    PullRequest *github.PullRequest 
+}
+```
+
+### ExecutionResult
+```go
+type ExecutionResult struct {
+    Output string         // AI原始输出
+    // ...其他审计字段
+}
+```
+
+---
+
+## 错误处理策略
+1. **关键步骤失败**：立即终止流程并返回错误
+   - 工作空间创建失败
+   - 分支创建失败
+   - AI 调用连续 3 次失败
+
+2. **非关键错误**：记录后继续执行
+   - 工作空间移动失败
+   - 非阻塞性的文件操作错误
+
+3. **错误信息展示**：自动在 PR Body 中标记错误段
+   ```markdown
+   ## 错误信息
+   ```text
+   {{error_details}}
+   ```
+   ```
+
+---
+
+## 扩展能力
+1. **多模型支持**：通过 `aiModel` 参数指定不同 AI 引擎
+2. **自定义 Prompt**：可通过 `args` 注入额外指令
+3. **审计追踪**：保留完整的 AI 交互记录在 PR 中
+
diff --git a/docs/cmd-continue.md b/docs/cmd-continue.md
@@ -0,0 +1,94 @@
+## /continue
+
+1. handler.go: 读取模型参数和其余args，要是没读到模型参数就使用默认模型
+2. handler.go: 169行，执行ContinuePRWithArgsAndAI()
+3. agent.go: 542, processPRWithArgsAndAI(xxx. "continue")
+4. agent: 384, GetOrCreateWorkspaceForPRWithAI（）*获取或创建 PR 工作空间，包含AI模型信息*, 
+5. agent:393, *拉取远端最新代码*
+6. *获取所有PR评论历史用于构建上下文*
+7. *构建包含历史上下文的 prompt*
+
+> ### 1. 初始化阶段
+> ```go
+> var prompt string
+> var taskDescription string
+> var defaultTask string
+> ```
+> 定义三个变量来存储最终结果和任务描述。
+>
+> ### 2. 模式判断（switch 语句）
+> 根据 `mode` 参数设置不同的任务描述：
+>
+> | 模式       | taskDescription                                              | defaultTask                      |
+> | ---------- | ------------------------------------------------------------ | -------------------------------- |
+> | "Continue" | "请根据上述PR描述、历史讨论和当前指令，进行相应的代码修改。" | "继续处理PR，分析代码变更并改进" |
+> | "Fix"      | "请根据上述PR描述、历史讨论和当前指令，进行相应的代码修复。" | "分析并修复代码问题"             |
+> | 其他       | "请根据上述PR描述、历史讨论和当前指令，进行相应的代码处理。" | "处理代码任务"                   |
+>
+> ### 3. 提示词构建逻辑（双重条件判断）
+>
+> #### 条件1：是否有具体指令（args != ""）
+> - **有指令 + 有历史上下文**：
+>   ```
+>   作为PR代码审查助手，请基于以下完整上下文来[模式]：
+>   
+>   [历史上下文]
+>   
+>   ## 当前指令
+>   [args]
+>   
+>   [taskDescription]注意：
+>   1. 当前指令是主要任务，历史信息仅作为上下文参考
+>   2. 请确保修改符合PR的整体目标和已有的讨论共识
+>   3. 如果发现与历史讨论有冲突，请优先执行当前指令并在回复中说明
+>   ```
+>
+> - **有指令 + 无历史上下文**：
+>   ```
+>   根据指令[模式]：
+>   
+>   [args]
+>   ```
+>
+> #### 条件2：是否有历史上下文（historicalContext != ""）
+> - **无指令 + 有历史上下文**：
+>   ```
+>   作为PR代码审查助手，请基于以下完整上下文来[模式]：
+>   
+>   [历史上下文]
+>   
+>   ## 任务
+>   [defaultTask]
+>   
+>   请根据上述PR描述和历史讨论，进行相应的代码修改和改进。
+>   ```
+>
+> - **无指令 + 无历史上下文**：
+>   ```
+>   [defaultTask]
+>   ```
+>
+> ## 逻辑流程图
+>
+> ```
+> 开始
+>   ↓
+> 设置 taskDescription 和 defaultTask（根据 mode）
+>   ↓
+> args != "" ?
+>   ├─ 是 → historicalContext != "" ?
+>   │         ├─ 是 → 构建完整提示词（包含历史上下文和当前指令）
+>   │         └─ 否 → 构建简单提示词（仅当前指令）
+>   └─ 否 → historicalContext != "" ?
+>             ├─ 是 → 构建基于历史上下文的提示词
+>             └─ 否 → 使用默认任务描述
+>   ↓
+> 返回构建好的 prompt
+> ```
+>
+
+8. 执行AI处理；resp, err := a.promptWithRetry(ctx, codeClient, prompt, 3) agent.go : 435
+
+9. *提交变更并更新 PR*, *Continue模式不返回错误，继续执行评论*
+
+10. 评论到 PR*