@aion0/forge 0.9.1 → 0.9.2

package/components/SettingsModal.tsx

@@ -546,6 +546,58 @@ export default function SettingsModal({ onClose }: { onClose: () => void }) {
           </p>
         </div>
 
+        {/* Pipeline tmp dir GC */}
+        <div className="space-y-2">
+          <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">
+            Pipeline scratch dir GC
+          </label>
+          <p className="text-[10px] text-[var(--text-secondary)] leading-snug">
+            Each pipeline run gets a scratch dir at <code>&lt;project&gt;/.forge/worktrees/pipeline-&lt;id&gt;/</code> exposed
+            to YAML as <code>{'{{run.tmp_dir}}'}</code>. Done runs are wiped immediately; failed / cancelled are
+            kept N days for inspection then swept by background GC.
+          </p>
+          <div className="flex items-center gap-2 flex-wrap">
+            <label className="text-[10px] text-[var(--text-secondary)] inline-flex items-center gap-1">
+              <input
+                type="checkbox"
+                checked={(settings as any).pipelineTmpCleanDoneImmediate !== false}
+                onChange={e => setSettings({ ...settings, pipelineTmpCleanDoneImmediate: e.target.checked } as any)}
+                className="accent-[var(--accent)]"
+              />
+              Wipe <code>done</code> runs immediately
+            </label>
+          </div>
+          <div className="flex items-center gap-2 flex-wrap">
+            <span className="text-[10px] text-[var(--text-secondary)]">Keep failed (days)</span>
+            <input
+              type="number"
+              min={0}
+              max={90}
+              value={(settings as any).pipelineTmpKeepFailedDays ?? 3}
+              onChange={e => setSettings({ ...settings, pipelineTmpKeepFailedDays: Math.max(0, Number(e.target.value) || 0) } as any)}
+              className="w-16 text-xs bg-[var(--bg-tertiary)] border border-[var(--border)] rounded px-2 py-1 text-[var(--text-primary)]"
+            />
+            <span className="text-[10px] text-[var(--text-secondary)] ml-2">Keep cancelled (days)</span>
+            <input
+              type="number"
+              min={0}
+              max={90}
+              value={(settings as any).pipelineTmpKeepCancelledDays ?? 3}
+              onChange={e => setSettings({ ...settings, pipelineTmpKeepCancelledDays: Math.max(0, Number(e.target.value) || 0) } as any)}
+              className="w-16 text-xs bg-[var(--bg-tertiary)] border border-[var(--border)] rounded px-2 py-1 text-[var(--text-primary)]"
+            />
+            <span className="text-[10px] text-[var(--text-secondary)] ml-2">GC sweep every (hours)</span>
+            <input
+              type="number"
+              min={1}
+              max={168}
+              value={(settings as any).pipelineTmpGcIntervalHours ?? 6}
+              onChange={e => setSettings({ ...settings, pipelineTmpGcIntervalHours: Math.max(1, Number(e.target.value) || 6) } as any)}
+              className="w-16 text-xs bg-[var(--bg-tertiary)] border border-[var(--border)] rounded px-2 py-1 text-[var(--text-primary)]"
+            />
+          </div>
+        </div>
+
         {/* Remote Access (Cloudflare Tunnel) */}
         <div className="space-y-2">
           <label className="text-xs text-[var(--text-secondary)] font-semibold uppercase">
@@ -835,7 +887,36 @@ function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete }: {
   onUpdate: (cfg: any) => void; onDelete: () => void;
 }) {
   const [expanded, setExpanded] = useState(false);
+  const [testing, setTesting] = useState(false);
+  const [testResult, setTestResult] = useState<{ ok: boolean; message?: string; error?: string; duration_ms?: number } | null>(null);
   const isApi = cfg.type === 'api';
+
+  async function runTest() {
+    setTesting(true);
+    setTestResult(null);
+    try {
+      // POST current in-memory values (apiKey/baseUrl/provider/model) so the
+       // user can test before clicking Save. Server falls back to saved values
+       // for anything we omit.
+      const r = await fetch(`/api/agents/${encodeURIComponent(id)}/test`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          apiKey: cfg.apiKey,
+          baseUrl: cfg.baseUrl,
+          provider: cfg.provider,
+          model: cfg.model,
+        }),
+      });
+      const j = await r.json();
+      setTestResult(j);
+    } catch (e) {
+      setTestResult({ ok: false, error: (e as Error).message || 'request failed' });
+    } finally {
+      setTesting(false);
+    }
+  }
+
   const summary = isApi
     ? `API: ${cfg.provider || '?'} / ${cfg.model || '?'}`
     : `CLI: ${cfg.cliType || cfg.base || '?'} / ${cfg.model || cfg.models?.task || 'default'}`;
@@ -895,6 +976,13 @@ function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete }: {
                 <div className="flex-1">
                   <label className="text-[8px] text-[var(--text-secondary)]">API Key</label>
                   <input type="password" value={cfg.apiKey || ''} onChange={e => onUpdate({ ...cfg, apiKey: e.target.value })} className={inputClass} />
+                  {(cfg.provider || '').toLowerCase() === 'anthropic' && (
+                    <div className="text-[8px] text-[var(--text-secondary)] mt-0.5 leading-snug">
+                      <code>sk-ant-api…</code> = standard pay-as-you-go key (recommended for chat).
+                      &nbsp;
+                      <code>sk-ant-oat…</code> = Claude Code OAuth — works, but shares your Pro/Max 5h quota and 429s quickly.
+                    </div>
+                  )}
                 </div>
               </div>
               <div>
@@ -923,6 +1011,24 @@ function ProfileRow({ id, cfg, inputClass, onUpdate, onDelete }: {
                   className={inputClass + ' font-mono'}
                 />
               </div>
+              <div className="flex items-center gap-2 pt-1">
+                <button
+                  onClick={runTest}
+                  disabled={testing || !cfg.apiKey}
+                  className="text-[9px] px-2 py-0.5 rounded bg-[var(--accent)]/10 text-[var(--accent)] hover:bg-[var(--accent)]/20 disabled:opacity-40 disabled:cursor-not-allowed"
+                  title={!cfg.apiKey ? 'Enter an API key first' : 'Probe GET /models against the provider'}
+                >
+                  {testing ? 'Testing…' : 'Test'}
+                </button>
+                {testResult && (
+                  <span className={`text-[9px] font-mono ${testResult.ok ? 'text-green-500' : 'text-red-400'}`}>
+                    {testResult.ok ? '✓' : '✗'} {testResult.message || testResult.error}
+                    {typeof testResult.duration_ms === 'number' && (
+                      <span className="text-[var(--text-secondary)] ml-1">({testResult.duration_ms}ms)</span>
+                    )}
+                  </span>
+                )}
+              </div>
             </>
           ) : (
             <>

package/docs/Team-Workflow-Integration.md

@@ -0,0 +1,487 @@
+
+# Forge 部门工作流集成 —— Design / Dev / QA 三团队 Playbook
+
+> Phase 1 目标:让部门内 **Design / Dev / QA** 三个团队的产出全部通过 Forge 打通,所有文档统一进 `pd-docs` GitLab 仓库,按 release / epic 双层组织。PM 与销售在本阶段是**输入源**而非 Forge 用户。
+>
+> 设计原则:**用 Forge 已有的能力(连接器、chat、jobs、crafts、Claude Code),不发明新概念。**
+
+
+## 0. 范围(Scope)
+
+### In scope —— 本期要做
+
+- Design / Dev / QA 三个内部团队的日常协作通过 Forge chat 进行
+- 单一 GitLab 仓库 `pd-docs` 承载所有 markdown 资料,按 release/epic 组织
+- 既有系统(PMDB、Mantis、GitLab)**通过 Forge 浏览器扩展连接器接入**,不做迁移
+- 关键节点(立项、提测、发版)用 Forge job 做自动化
+
+### Out of scope —— 本期不做
+
+- PM / 销售直接进 Forge(他们继续用 PMDB,Forge 单向读)
+- 替代 PMDB / Mantis(只是把它们做成 Forge 的工具,不动数据归属)
+- 跨部门 / 跨公司的 marketplace
+- 完整的发版自动化(只做 release notes 草稿,不接 CI/CD)
+- **TP 系统**:由 QA 自己开发/维护,**QA 继续用**(本期不动);Dev / PM 内部跟踪改走 GitLab Epic+Issue
+
+### 关键决策
+
+| # | 决策 | 选择 | 备注 |
+|---|---|---|---|
+| 1 | TP 系统 | **QA 继续用,Dev/PM 侧用 GitLab Epic+Issue 替代** | TP 是 QA 自研系统,不进 Forge 集成范围;但 QA 工作流仍可保留 TP 引用(可选) |
+| 2 | Mantis vs GitLab 分工 | **Mantis = 公司主要管理工具(NFR 立项 + Bug 追踪,合规必走);GitLab = Dev 内部推动使用(Epic + Issue + MR)** | 两套并存,各管各的;**Epic ID 命名带 Mantis NFR 编号**,可互查 |
+| 3 | pd-docs 写权限 | **所有人有 push 权限,但 merge 到 master 必走 MR** | 用户确认 |
+| 4 | 测试自动化脚本 | **QA 自己负责**,跟测试用例同仓库(`06-test/automation/`) | QA owns it end-to-end |
+| 5 | PMDB → git 同步 | **Forge job 定时拉**,落到 `pd-docs/inbox/`,Design 从 inbox 挑需求建 epic | 不要求 PM/销售配合,自动化 |
+
+
+## 1. 角色与系统映射
+
+### 角色
+
+| 角色 | 在本流程的职责 | 主用 Forge 功能 |
+|---|---|---|
+| **Design team** | 调研 / 沟通 / 写 PD 设计方案 | chat 起草 PD,Mantis/PMDB 连接器,文件 commit |
+| **Dev (技术负责人)** | 拆模块 / 写技术设计 / 分配子任务 | chat + Claude Code 起草技术设计,GitLab Issue 连接器 |
+| **Dev (模块负责人)** | 实现子功能,开 MR | GitLab MR 连接器,Forge pipeline |
+| **QA** | 测试用例,自动化脚本,回归 | chat 起草用例,Mantis bug 连接器 |
+| **Manager** | review 设计/技术方案,版本规划 | Forge craft(release dashboard) |
+| ~~PM / 销售~~ | 在 PMDB 录入需求 | (不进 Forge) |
+
+### 系统映射
+
+| 系统 | 当前角色 | 如何接入 Forge |
+|---|---|---|
+| PMDB | 需求入口,PM/销售写 | 浏览器扩展连接器(只读)+ Forge job 定时同步到 `pd-docs/inbox/` |
+| Mantis | **公司主要管理工具**:NFR 立项 + Bug 追踪(合规必走) | 浏览器扩展连接器(读 + 写) |
+| GitLab `pd-docs` | 文档单一仓库 | 浏览器扩展连接器 + 本地 clone |
+| GitLab 代码仓库 | **Dev 内部推动使用**:代码 + Epic + Issue + MR | 浏览器扩展连接器 + GitLab API |
+| TP | QA 自研系统,QA 继续使用 | **不进 Forge 集成**(QA 视情况手动同步) |
+| Forge chat | 协作主界面 | 主用 |
+| Claude Code | 长文本起草 / 代码生成 | Forge chat 触发,在本地 pd-docs cwd 跑 |
+| Forge jobs | 自动化:PMDB 同步 / 立项 / 周进度 / bug 日报 / release notes | 主用 |
+| Forge craft | release dashboard(可选,后期) | 后期 |
+| Teams | 评审通知 / 公告 | 浏览器扩展连接器(消息发送) |
+
+
+## 2. 资料共享:`pd-docs` GitLab 仓库结构
+
+### 设计原则
+
+- **markdown only** —— 所有 stage 产出都是 `.md`,Forge chat 和 Claude Code 都能直接读
+- **release / epic 双层目录** —— 一眼看到这个版本要交付什么
+- **EPIC-编号 == Mantis NFR 编号 == GitLab Epic 编号** —— 三处可互查,人脑只记一个数字
+- **文件名日期前缀** —— 同 stage 多次产出按时间序排
+- **每个 epic 目录骨架由 Forge job 自动建立** —— 立项时一键生成,人不用复制模板
+
+### 目录结构
+
+```
+pd-docs/                                         # GitLab 仓库
+├── README.md                                    # 索引 + 命名规范 + Forge 使用 cheatsheet
+├── templates/                                   # 各阶段模板,立项时被复制
+│   ├── 00-intake.md                             # PMDB 链接 + 销售原始描述
+│   ├── 01-discovery-meeting.md                  # 客户/PM 访谈纪要
+│   ├── 02-design.md                             # PD 设计方案主文档
+│   ├── 03-review.md                             # 评审纪要
+│   ├── 04-tech-design.md                        # 技术设计
+│   ├── 06-test-cases.md                         # 测试用例
+│   └── 07-release.md                            # 上线记录
+├── inbox/                                       # Forge job 定时从 PMDB 拉的"未处理"需求
+│   ├── 2026-04-08-PMDB-7821.md                  # 文件名带日期 + PMDB ID
+│   └── 2026-04-09-PMDB-7825.md
+├── releases/
+│   ├── 2026-Q3/
+│   │   ├── README.md                            # 本 release 范围、Epic 清单、关键时间点
+│   │   ├── EPIC-1234-SAML-SSO/
+│   │   │   ├── 00-intake.md
+│   │   │   ├── 01-discovery/
+│   │   │   │   ├── 2026-04-12-customer-acme.md
+│   │   │   │   └── requirements.md
+│   │   │   ├── 02-design.md
+│   │   │   ├── 03-review/
+│   │   │   │   ├── 2026-04-25-r1.md
+│   │   │   │   └── 2026-05-08-r2.md
+│   │   │   ├── 04-tech-design/
+│   │   │   │   ├── overview.md
+│   │   │   │   ├── module-auth.md
+│   │   │   │   └── module-config.md
+│   │   │   ├── 05-implementation/               # 开发期决策、调研、坑记录
+│   │   │   ├── 06-test/
+│   │   │   │   ├── test-cases.md
+│   │   │   │   ├── test-plan.md
+│   │   │   │   └── automation/                  # 自动化脚本
+│   │   │   └── 07-release.md
+│   │   └── EPIC-1235-XXX/
+│   └── 2026-Q4/
+└── shared/                                      # 跨 release 通用资料
+    ├── architecture/                            # 部门级架构图(每年更新)
+    └── glossary.md                              # 术语表
+```
+
+### Forge chat 怎么"读这个仓库"
+
+技术上有两种方式:
+
+1. **本地 clone**:Forge 后端跑在内网机器上,定时 `git pull pd-docs`。chat 工具 `read_pd_doc(path)` 直接读本地文件 —— **快,低开销**。
+2. **GitLab API 连接器**(浏览器扩展端):chat 调用 `gitlab.get_file(path)` 拉单个文件 —— **慢但解耦,适合 Forge 后端不在内网的情况**。
+
+Phase 1 用方式 1(简单)。
+
+
+## 3. 整体工作流(stage 维度)
+
+| # | Stage | 主角色 | 输入 | 产出 | 周期 |
+|---|---|---|---|---|---|
+| 1 | Intake | PM/销售(Forge 外) | 业务需求 | PMDB 条目 | <1 周 |
+| 2 | Discovery | Design | PMDB 条目 | `01-discovery/*.md` | 2-4 周 |
+| 3 | Design | Design | 调研 + 历史 PD | `02-design.md` | 1-3 周 |
+| 4 | Review | Dev + Design + Manager | `02-design.md` | `03-review/*.md` + 定稿 | 1-2 周 |
+| 5 | Formalize | Manager + 技术负责人 | 定稿 PD | Mantis NFR + GitLab Epic + 目录骨架 | 1-2 天 |
+| 6 | Release Plan | Manager | Epic 列表 | Epic milestone | 1 周 |
+| 7 | Tech Design | 技术负责人 + 模块负责人 | `02-design.md` | `04-tech-design/*.md` + 子 issue | 2-4 周 |
+| 8 | Implementation | 模块负责人 | 子 issue + 技术设计 | MR → merge | 4-12 周 |
+| 9 | QA | QA + Dev | PD + 技术设计 + 代码 | `06-test/*` + bug 报告 | 2-4 周 |
+| 10 | Release | Manager + 发版 | merged Epic | GitLab release + `07-release.md` | <1 周 |
+
+**总周期 3-6 月**,跟现有版本节奏一致。
+
+
+## 4. Design 团队工作流(详细)
+
+### Stage 2: Discovery —— 调研沟通
+
+**目标**:把 PMDB 里一条粗糙的需求,变成"我们要做什么、给谁、为什么"的明确陈述。
+
+**步骤**:
+
+1. **Forge job 已经自动同步 PMDB 到 `pd-docs/inbox/`**(每小时跑一次,新增需求自动落地)。Design 团队每天早上 chat 输入:
+   > "列下 inbox 里本周新增的需求"
+
+   chat 直接读本地 `pd-docs/inbox/` 列表,Design 不用打开 PMDB 网页。
+
+2. 选定一条要做的,**chat 触发立项草稿**:
+   > "把 PMDB-7821 作为新 epic,起一个工作目录"
+
+   背后 Forge job 跑:
+   - 在 `pd-docs` 仓库建 `releases/未规划/EPIC-TBD-{slug}/` 目录
+   - **从 inbox 里 move `2026-04-08-PMDB-7821.md` 到新 epic 的 `00-intake.md`**(避免重复)
+   - 复制其他 stage 模板进去
+
+3. 约客户 / PM / 销售开会(线下/Teams)。
+
+4. **会后,chat 起会议纪要**:
+   > "刚跟客户 ACME 开了 30 分钟,主要谈了 SSO 改造,他们的痛点是 [...]。
+   > 帮我整理成一份 discovery 纪要,放到当前 epic 下"
+
+   Chat 生成 markdown,落到 `01-discovery/2026-04-12-customer-acme.md`,**commit 一个分支**(MR 进 master)。
+
+5. 重复 2-3 次,直到 `01-discovery/requirements.md` 整理出明确的 "what / why / who / out-of-scope"。
+
+**Forge 实际帮上的忙**:
+- PMDB 连接器,**不用切到 PMDB 页面**
+- chat 写 markdown,**比自己排版快**
+- 同类历史 epic 的检索:`"找 pd-docs 里所有提过 SAML 的 epic"` → chat 在本地 clone 上跑 grep
+
+### Stage 3: Design —— 写 PD 设计方案
+
+**目标**:产出 `02-design.md`,包含设计 + 实现方案的初版,**够让研发开始 review**。
+
+**步骤**:
+
+1. **chat 起 PD 骨架**:
+   > "基于这个 epic 的 discovery 资料,起一份 PD 草稿,
+   > 参考 EPIC-1100 的 PD 结构"
+
+   Chat 读 `01-discovery/*` + `releases/*/EPIC-1100/02-design.md`,**生成 PD 骨架**。
+
+2. Design 自己填充细节(架构图、字段定义、API 草案)。架构图用 Excalidraw,放在 `02-design.md` 同目录,文件名同名 `.excalidraw.svg`。
+
+3. **chat 自检**:
+   > "这份 PD 哪里写得不够具体,有哪些没回答的问题?"
+
+   chat 给出 review 清单。Design 根据清单补。
+
+4. PD 满意后 commit + push,触发**自动 MR 到 master**。**MR description 由 chat 起草**(改了什么、为什么)。
+
+**Forge 实际帮上的忙**:
+- 历史 PD 检索 + 套结构
+- PD 自检 prompt
+- MR description 起草
+
+
+## 5. Dev 团队工作流(详细)
+
+### Stage 4: Review —— 设计评审(多轮)
+
+**目标**:研发对 `02-design.md` 提出问题/反对/改进,Design 改,直到通过。
+
+**步骤**:
+
+1. PD 被 push 到 master 后,**Forge job 自动**:
+   - Teams 连接器发消息到研发组群:"`EPIC-TBD-SAML-SSO` 的 PD 提交了,请 review"
+   - 在 `03-review/` 下建 `2026-04-25-r1.md` 模板,等填
+
+2. 研发自己开 Forge chat:
+   > "把 EPIC-TBD-SAML-SSO 的 PD 给我总结一遍重点"
+
+   chat 读 `02-design.md`,给一段 300 字总结。
+
+3. 研发提问/反对,Design 在会上记下,**chat 帮归类**:
+   > "帮我把刚才会上提的 12 个问题分类:必须改的、待讨论的、out-of-scope"
+
+   chat 落到 `03-review/2026-04-25-r1.md`。
+
+4. 多轮后,PD 定稿。**chat 标记定稿版本**:
+   > "把 02-design.md 当前内容打 v1.0 tag"
+
+   触发 git tag。
+
+### Stage 5: Formalize —— 正式立项
+
+**目标**:把"草稿目录"变成正式 epic。
+
+**步骤**:
+
+1. Manager 或技术负责人在 chat 输入:
+   > "立项 EPIC-TBD-SAML-SSO,目标版本 2026-Q3"
+
+2. **Forge job 跑一连串自动化**:
+   - **Mantis 连接器**:在 Mantis 建一个 NFR,返回编号 `MA-9981`
+   - **GitLab API**:在代码仓库建 Epic `EPIC-9981-SAML-SSO`(编号沿用 Mantis NFR)
+   - **pd-docs 仓库**:目录 rename `EPIC-TBD-SAML-SSO/` → `EPIC-9981-SAML-SSO/`,移动到 `releases/2026-Q3/` 下
+   - **Forge chat 会话**:绑定到这个 epic,后续 chat 默认上下文是这个目录
+
+3. **chat 通知技术负责人**:Teams 发消息 + 邮件(Teams 连接器)。
+
+### Stage 6: Release Plan —— 版本规划
+
+不复杂,Manager 在 GitLab Epic 上设 milestone。
+
+(后期可以做 Forge craft 作为 release dashboard,聚合 release 里所有 Epic 的进度 + 子 issue + bug 数。**Phase 1 不做。**)
+
+### Stage 7: Tech Design —— 技术设计
+
+**目标**:技术负责人(主)+ 模块负责人(辅),产出 `04-tech-design/` 下的多份文档,拆出 GitLab 子 issue。
+
+**步骤**:
+
+1. **技术负责人在 chat 起整体技术设计**:
+   > "基于 EPIC-9981 的 PD,起一份技术设计 overview。
+   > 重点是改造 auth 模块、新增 SAML config 模块,
+   > 我们的 Java 代码在 fortinac 仓库 src/main/java/com/foo/auth"
+
+   chat 触发 Claude Code 在本地 `fortinac` cwd 跑,产出 `04-tech-design/overview.md`。Overview 包含:模块拆分、接口契约、关键风险、子任务清单。
+
+2. **拆模块,分配负责人**(人脑决策,不需要 Forge 帮)。
+
+3. **每个模块负责人在 chat 起子模块技术设计**:
+   > "我是 auth 模块负责人,我需要起 module-auth.md"
+
+   chat 读 `overview.md` + 相关代码,产出 `04-tech-design/module-auth.md`。
+
+4. **批量创建 GitLab 子 issue**:
+   > "把 overview.md 里的子任务清单转成 GitLab issue,
+   > 关联到 EPIC-9981"
+
+   Forge job 调用 GitLab API,**一次创建 N 个子 issue,自动 link 到 epic**。每个 issue 描述里贴对应技术设计文档的 GitLab 链接。
+
+**Forge 实际帮上的忙**:
+- Claude Code 在代码仓库 cwd 跑,**起的技术设计自动带具体类名/文件路径**(不像纯 chat 会瞎编)
+- 子 issue 批量创建(节省 30 分钟纯手工)
+
+### Stage 8: Implementation —— 开发
+
+**目标**:模块负责人按子 issue 实现,提 MR。
+
+**步骤(对每个子 issue)**:
+
+1. 模块负责人 checkout 分支,本地开发(可用 Claude Code)。
+
+2. **MR 自动关联**:开 MR 时 description 里写 `Closes #123`,GitLab 自动关联子 issue 到 epic。
+
+3. **MR review 时**,reviewer 可以在 Forge chat 输入:
+   > "@gitlab 总结 MR !4427 的改动重点"
+
+   chat 用 GitLab 连接器拉 diff,给摘要。
+
+4. **进度跟踪**:Forge job 每周一早上跑,生成本周进度简报,写到 `EPIC-9981/05-implementation/2026-W19-status.md`。简报包含:closed/open issue 比例、本周 merge MR 数、blocker 摘要(从 GitLab issue 评论里抓"blocked"标记)。
+
+
+## 6. QA 团队工作流(详细)
+
+### Stage 9: QA —— 测试
+
+**目标**:`06-test/` 下产出完整测试用例 + 自动化脚本,跑测试,bug 进 Mantis。
+
+**步骤**:
+
+1. **QA 在 chat 起测试用例草稿**:
+   > "EPIC-9981 准备提测,基于 PD + 技术设计起一份测试用例"
+
+   chat 读 `02-design.md` + `04-tech-design/*.md`,生成 `06-test/test-cases.md`。用例分类:
+   - 正向用例(主流程)
+   - 异常用例(边界 / 错误处理)
+   - 兼容性用例(浏览器 / 旧版本配置)
+   - 性能/安全用例(只对关键 Epic 写)
+
+2. QA review + 补 chat 没想到的(domain 知识),commit 进 `pd-docs`。
+
+3. **自动化脚本草稿**:
+   > "把上面的正向用例转成 Playwright 脚本"
+
+   chat 触发 Claude Code 在 QA 仓库 cwd 跑,落地 `06-test/automation/saml-login.spec.ts`。**自动化覆盖率不是目标,先覆盖回归用例就够**。
+
+4. **跑测试,发 bug 到 Mantis**:
+   - chat 输入 "在 Mantis 建一个 bug:[复现步骤] [期望] [实际]"
+   - Mantis 连接器创建 bug,关联到 NFR `MA-9981`
+
+5. **bug 跟踪**:Forge job 每天跑一次,把本 epic 下未关闭的 bug 列到 `06-test/bug-status.md`,**chat 直接读这个文件做日会汇报**。
+
+**Forge 实际帮上的忙**:
+- 从 PD + 技术设计起测试用例,QA **不用重新读一遍设计**
+- 自动化脚本起草(覆盖 70%,QA 改 30%)
+- bug 创建 / 跟踪 / 汇报自动化
+
+
+## 7. Forge 在每个 stage 的具体能力清单
+
+汇总一张表(不重复内容,标用到的 Forge 能力):
+
+| Stage | Forge 能力 | 现状 | 备注 |
+|---|---|---|---|
+| Intake | PMDB 浏览器连接器(只读) | 需新写 YAML(15 分钟) | 列需求 / 读详情 |
+| Intake | PMDB → inbox 同步 job | 需新 Forge job(scheduled,每小时) | 写入 `pd-docs/inbox/` |
+| Discovery | chat 读 inbox | ✅ 已有 | 直接读本地 markdown |
+| Discovery | chat 起会议纪要 | ✅ 已有 | |
+| Discovery | 历史 epic grep | ✅ 已有(本地 clone) | |
+| Design | chat 起 PD 草稿 | ✅ 已有 | |
+| Design | PD 自检 prompt | 需固化 prompt 模板 | |
+| Review | Teams 连接器发通知 | 需新写 YAML | 已有 isolated runner |
+| Review | chat 归类反馈 | ✅ 已有 | |
+| Formalize | Mantis 连接器(写) | 需扩展现有连接器,加 create_nfr 工具 | 需 destructive 标记 + consent |
+| Formalize | GitLab API 建 Epic | 需新连接器 / HTTP 协议 | |
+| Formalize | pd-docs 目录重命名 + git 操作 | 需新 Forge job | |
+| Tech Design | Claude Code 本地 cwd | ✅ 已有 | |
+| Tech Design | GitLab API 批量建子 issue | 同上 | |
+| Implementation | GitLab MR diff 摘要 | 需新连接器读 MR | |
+| Implementation | 每周进度 job | 需新 job(scheduled) | |
+| QA | chat 起测试用例 | ✅ 已有 | |
+| QA | Claude Code 起自动化脚本 | ✅ 已有 | |
+| QA | Mantis bug 创建 | 需扩展现有连接器 | |
+| QA | bug 状态日报 | 需新 job | |
+
+**总计需要新建/扩展**:
+- 2 个连接器(PMDB 读、GitLab API)
+- 现有 2 个连接器各加几个写工具(Mantis create_nfr/create_bug、Teams send_message 已经有)
+- **4 个 Forge job**(**PMDB→inbox 同步**、立项、周进度、bug 日报)
+- 1 个 prompt 模板(PD 自检)
+
+
+## 8. 分阶段落地路线
+
+**别一口气全做。按依赖关系拆 4 个 milestone:**
+
+### M0: 基础设施(1 周)
+
+- [ ] 建 `pd-docs` GitLab 仓库
+- [ ] 写 `templates/` 下所有 stage 的模板
+- [ ] 写 `README.md`,定义命名规范 + Forge 使用 cheatsheet
+- [ ] Forge 后端机器 `git clone pd-docs`,设置 systemd timer 每 10 分钟 `git pull`
+- [ ] 一个示范 epic(挑历史一个已完成的,reverse engineer 一份样板)
+
+### M1: Design team 接入(2-4 周)
+
+- [ ] PMDB 连接器(只读 YAML,~50 行)
+- [ ] **PMDB → `pd-docs/inbox/` 同步 job(scheduled,每小时)**
+- [ ] PD 自检 prompt 固化到 chat skill
+- [ ] Design team 至少 1 个新 epic 全流程跑通(2-3 → commit 到 `pd-docs`)
+- [ ] 反馈一轮,调模板和 prompt
+
+**M1 验收**:Design 不再用 Word/wiki,所有新 PD 直接在 Forge chat 起草 + commit pd-docs。
+
+### M2: Dev team 接入(2-4 周)
+
+- [ ] GitLab API 连接器(用 HTTP protocol,~100 行 YAML + token 配置)
+- [ ] Mantis 连接器扩展:加 `create_nfr` 工具
+- [ ] Forge job:立项自动化(建 NFR + Epic + 目录重命名)
+- [ ] Forge job:每周进度简报
+- [ ] 技术负责人按新流程跑通 1 个 epic 的 review + tech design + 拆 issue
+
+**M2 验收**:立项一键完成,技术设计在 chat 里起草并 commit pd-docs,子 issue 批量创建。
+
+### M3: QA team 接入(2-4 周)
+
+- [ ] Mantis 连接器扩展:加 `create_bug` 工具
+- [ ] Forge job:bug 状态日报
+- [ ] QA 按新流程跑通 1 个 epic 的测试用例 + 自动化脚本草稿 + bug 跟踪
+
+**M3 验收**:QA 测试用例和自动化脚本都进 pd-docs,bug 通过 chat 创建。
+
+### M4: 巩固 / 后续(常态)
+
+- 每月 retro,改 prompt / 模板 / job
+- 视情况做 release dashboard craft(如果 manager 真的需要)
+- 跨部门推广(out of phase 1)
+
+
+## 9. 常见反对与回应
+
+**Q: 为什么不直接用 Notion / 公司 wiki?**
+A: Forge chat 要能直接 read 文档做检索 / 起草。Notion / 公司 wiki 没有干净的 API,而 markdown + git 是 Claude Code 和 chat 天然能处理的格式。**markdown 不绑死任何工具**,Forge 没了文档还在 git。
+
+**Q: pd-docs 一个仓库会不会太大?**
+A: 一个 epic 一般产出 < 1 MB markdown + 几张 svg。一年 10-20 个 epic,5 年内不会超 100 MB。GitLab 没压力。
+
+**Q: 立项时 Mantis NFR 和 GitLab Epic 两边同步会不会偏移?**
+A: NFR 只在立项创建一次,之后只读(合规留痕)。日常执行只看 GitLab Epic。两边没有"同步"问题,各管各的。
+
+**Q: 如果 PMDB 改了需求,谁负责把 `00-intake.md` 同步更新?**
+A: 默认手动 —— Design 发现需求变了,在 chat 触发"重新拉 PMDB-7821 更新当前 epic 的 intake"。**不做定时 polling,降低复杂度。**
+
+**Q: 评审记录会不会被人偷偷改?**
+A: git 历史可追溯。任何 commit 都能 blame 出来。如果团队不放心,可以加 commit signing。
+
+**Q: Forge 后端挂了影响整个流程吗?**
+A: pd-docs 是 GitLab 仓库,Forge 没了仓库还在,人可以直接 git 操作。Forge 是**协作加速器**,不是 single point of failure。
+
+
+## 10. 待澄清(下一轮 review 解决)
+
+1. **pd-docs 仓库放在哪个 GitLab group?** 部门私有 group 还是研发 group?
+2. **PMDB 连接器读什么字段?** 至少需要:标题、描述、提出人、状态、客户、优先级。需 PMDB 页面长啥样看一眼。
+3. **Mantis NFR 字段:** 立项时需要预填哪些?(优先级、负责人、目标版本)
+4. **Forge 后端部署在哪台机器?** 决定了 `pd-docs` 本地 clone 路径和 systemd timer 配置。
+5. **PMDB → inbox 同步频率:** 默认每小时,有更急需求时是不是要做到 15 分钟?
+6. **TP 系统在 QA 工作流的角色:** QA 是否需要 Forge 在创建 Mantis bug 后**同时也往 TP 写一条**?还是 QA 手动二次录入?
+7. **Design team 谁负责试跑 M1?** 至少需要 1 个人配合,出来反馈调 prompt / 模板。
+
+
+## 附录 A: 一个完整 epic 时间线示例(假想)
+
+```
+2026-04-08  PM 在 PMDB 录入 "客户 ACME 要 SAML SSO" (PMDB-7821)
+2026-04-08  Forge job 同步进 pd-docs/inbox/2026-04-08-PMDB-7821.md(1h 内)
+2026-04-10  Design Liu 看 inbox,chat "把 PMDB-7821 作为新 epic"
+2026-04-12  跟 ACME 开会,chat 落地 01-discovery/2026-04-12-customer-acme.md
+2026-04-15  跟 PM 复核,chat 落地 01-discovery/requirements.md
+2026-04-20  chat 起 02-design.md 草稿,Liu 补细节,push,触发评审通知
+2026-04-25  研发 r1 评审,chat 落地 03-review/r1.md,Liu 改 PD
+2026-05-08  研发 r2 评审,通过
+2026-05-09  Manager 在 chat "立项 EPIC-TBD-SAML-SSO 目标 2026-Q3"
+             ↓ Forge job 跑 ~30s:
+             ↓   Mantis NFR MA-9981 创建
+             ↓   GitLab Epic !9981 创建
+             ↓   目录重命名 + 移到 releases/2026-Q3/
+             ↓   Teams 通知技术负责人 Zhang
+2026-05-10  Zhang 在 chat 起 04-tech-design/overview.md(用 Claude Code)
+2026-05-15  拆模块,3 个模块负责人分别起 module-*.md
+2026-05-18  批量建 12 个 GitLab 子 issue
+2026-05-19 ~ 2026-07-15  开发 + MR + 周进度简报
+2026-07-16  提测,QA Chen 在 chat 起 06-test/test-cases.md
+2026-07-20  自动化脚本草稿
+2026-07-22 ~ 2026-08-05  测试,5 个 bug 进 Mantis,修复
+2026-08-12  发版,Manager 触发 chat 生成 07-release.md(从 epic 下所有 MR 取 changelog)
+2026-08-15  上线
+```
+
+**总周期 ~4 个月,落在 3-6 个月窗口内。**