AGENTS.md git:20260906.400d95cA

Immutable. This exact content is served forever at /api/v1/blob/54c37c0b341ecfb9.

# AGENTS.md

## 项目概述

dsh-visual-workflow 是 DeepSeek Harness（dsh）生态的 **host + client 双面可视化多 Agent 工作流设计器插件**

- **需求文档**：`docs/需求文档.md`
- **架构文档**：`docs/架构文档.md`
- 审查时**必须逐条对照上述两份文档**，任何偏离均视为 BUG。

### 文档索引（用 read(offset, limit) 按任务需求读取片段，不要读取整个文件）

**架构文档**：

- 1. 架构总览 - 起始行号：L11
- 2. 插件契约 - 起始行号：L28
   定义包名、入口、exports、挂载配置与 peer 依赖等 
- 3. 目录结构（本项目） - 起始行号：L97  **不要读**
- 4. Host 半区模块设计 - 起始行号：L130
- 5. 关键协议与时序 - 起始行号：L313
   运行启动、暂停与断点续跑、wf_ask_agent通信、协作组并行、模式二请求流 
- 6. 数据与模型资产 - 起始行号：L382
   run 快照、服务状态、模板、导入导出 v2 bundle、本地嵌入模型与向量索引   
- 7. 模式二 serve 层（serve.patch.yml 模板） - 起始行号：L476 
- 8. 官方源码引用索引（核心功能 -> 官方源码位置） - 起始行号：L498
- 9. 安全、权限与边界 - 起始行号：L529
- 10. Client 半区设计（由旧项目迁移；P11 起入口改版） - 起始行号：L540  
- 11. 测试与验证矩阵 - 起始行号：L552  **必读**
- 12. 风险与实现时验证项 - 起始行号：L564
- 13. 编码与提示词工程规范（横切，所有任务必须遵守） - 起始行号：L576  **必读**

**需求文档**：

- 1. 产品背景  - 起始行号：L9  
- 2. 术语与缩写定义  - L27  **必读**
- 3. 核心流程  - L55  
  - 3.1 模式一：流程编排模式  - L57  
    流程：拖拽配置→运行→暂停/续跑，断点续跑与双向同步  
  - 3.2 模式二：API服务模式  - L76  
    服务启动、API请求、多用户隔离及流式响应
- 4. 功能需求  - L96  
  - 4.1 双模式架构模块  - L98  
  - 4.2 节点管理模块  - L189  
  - 4.3 连线管理模块  - L469  
  - 4.4 工具扩展模块  - L512  
  - 4.5 UI 交互模块  - L583 
  - 4.6 组合管理模块  - L643  
  - 4.7 运行历史与断点恢复  - L663  
- 5. 非功能需求  - L688  
- 6. 开放问题清单  - L720  
- 8. 设计约束  - L741  **必读**
- 9. 复用与差异清单（旧项目 → 新项目）  - L755 ~ 804

## 开发环境

| 工具 | 版本 | 备注 |
|------|------|------|
| node | v24.17.0 | |
| pnpm | 11.22.0 | 包管理器（不要用 npm/yarn） |
| git | 2.53.0.windows.2 | 仓库主分支 main |
| dsh CLI | 0.1.1-rc.2 | 全局安装 `@deepseek-ai/dsh@0.1.1-rc.2`；Windows 路径 `C:\Users\GZX\AppData\Roaming\npm\dsh.ps1` |

### 版本镜像约定

与官方仓库 devDependencies 对齐：

| 包 | 版本 | 用途 |
|----|------|------|
| typescript | ^6.0.3 | 双 program 编译（官方同款） |
| tsdown | ^0.22.2 | client bundle 构建（复用官方 tsdown.client.ts 模式） |
| vitest | ^4.1.8 | host/client 单测 |
| jsdom | 29.1.1 | client 单测环境 |
| @huggingface/transformers | 架构文档指定 | 唯一第三方**运行时**依赖（本地嵌入推理） |

- react / react-dom 仅为 **devDependencies**：client bundle 由官方平台模块表提供，构建期从 `lib/` 找回资源。

## 构建与测试命令

```bash
pnpm typecheck      # tsc 双 program 类型检查（host + client + test）
pnpm build          # node scripts/build.mjs（tsc 发射 JS + tsdown 构建 client bundle）
pnpm test           # vitest run --pool=threads
pnpm client-smoke   # node scripts/client-smoke.mjs
pnpm check          # typecheck + test + build + client-smoke（推荐合并命令）
pnpm verify         # typecheck + build + test + client-smoke
```

- 构建产物在 `lib/`；`lib/types/` 存放声明文件。

## 目录结构

```
dsh-visual-workflow/
├── src/
│   ├── host/                     # Host 插件
│   │   ├── shared/               # 前后端共享纯类型契约
│   │   ├── storage/              # 原子存储（FlowStore）
│   │   ├── orchestrator/         # 运行锁、断点状态机、双向同步
│   │   ├── agent/                # 子代理执行引擎、护栏、提示词注入
│   │   ├── tools/                # wf_* 工具注册
│   │   ├── remote/               # GUI API 端点
│   │   ├── service/              # 模式二服务管理器（fork/端口池/恢复）
│   │   ├── embedding/            # 本地向量嵌入与索引
│   │   ├── scheduler/            # 定时任务引擎
│   │   └── prompts/              # 编排/节点任务提示词模板
│   └── client/                   # WebUI 源码
│       ├── studio/               # 主状态机（useReducer）
│       ├── components/           # 画布/面板/组合/历史/定时任务等
│       ├── hooks/                # 职责单一 hooks
│       └── lib/                  # 纯逻辑（remote/graph-model/bundle）
├── tests/                        # 单元 + 集成测试
├── scripts/                      # 构建与 watch 脚本
├── assets/models/                # 本地嵌入模型资产
├── cordis.patch.yml              # Web profile 挂载层
├── serve.patch.yml               # 模式二服务进程组合层模板
├── docs/                         # 需求文档 / 架构文档 / MCP注册指南
└── package.json
```

- `src/host/shared/` **禁止任何 import，禁止运行时值**（函数/常量一律不放）。client 经 `import type` 零风险引用。
- 双 program 完全隔离：`tsconfig.host.json`（nodenext + node types）与 `tsconfig.client.json`（bundler + dom types）互不 include。

## 硬性架构约束（违反即 BUG）

1. **零官方包运行时依赖**：`@deepseek-ai/*` 仅经 `ctx.get()` 运行时解析，工具以纯对象 `defineTool` 定义注册。唯一允许的第三方运行时依赖是 `@huggingface/transformers`（本地嵌入推理）。`@deepseek-ai/schemastery` 仅 devDependency。
2. **不得修改 dsh 底层核心框架**，全部基于非侵入式扩展（patch 层、事件观察、ctx service）。
3. **节点 JSON 即事实源**：模板与画布节点深拷贝解耦，节点数据全量内联，无 `templateId` 引用。
4. **双模式解耦**：模式二服务进程 = fork 独立无头 DSH 实例，崩溃不得影响主进程。
5. **提示词工程**（架构文档 §13）：
   - 前缀稳定：系统提示/工具 schema 顺序固定，动态值**仅注入末段**（`TAIL_MARKER` 之后）。
   - 关键约束双位：首段 + 末段重申（`HEAD_MARKER` / `TAIL_RESTATE_MARKER`）。
   - 提示词模板构建器均为**纯函数**，不读 `Date.now`/随机源。
   - 工具 `description` 用官方标准英文（≤120 tokens）；代码注释、JSDoc、README 用中文。

## 代码风格

- TypeScript strict 模式，`verbatimModuleSyntax: true`（type 导入必须用 `import type`）。
- React + 函数组件 + hooks；状态管理使用 `useReducer`（reducer 在 `studio/studio-state.ts`），所有变更经 `dispatch(action)` 单向流转。
- 纯函数优先：图模型操作、提示词构建器、连线校验、BM25 打分等核心逻辑不依赖全局状态、不读时钟/随机源（便于单测）。
- 依赖注入缝：运行时服务（`ctx.get`）通过接口最小化后注入，便于 fake 测试。
- 错误处理：后端 `WfError` 带稳定 code（`WF_*`）；前端 `useToast` 统一展示。
- 原子写协议：所有持久化经 `withJsonLock` + `atomicWriteJson`（临时文件 + fsync + rename），不得绕过直接写文件。

## 其他约定

- 文档更新：修改 `shared/protocol.ts`（端点名）、`shared/types.ts`（数据结构）、`shared/graph-model.ts`（节点/连线模型）后，**必须同步更新 `docs/架构文档.md`** 对应章节，保持文档与代码零漂移
- 修改核心引擎（orchestrator/agent/tools）后必须运行 `pnpm test`；修改前后端契约（shared/protocol.ts、shared/types.ts、shared/graph-model.ts）后必须运行 `pnpm typecheck` 并检查前端编译
- 不允许阅读项目根目录下 prompt/ 文件夹内的任何文件（除我指定之外）